diff options
Diffstat (limited to 'doc/en')
63 files changed, 5249 insertions, 0 deletions
diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am new file mode 100644 index 0000000..cd97965 --- /dev/null +++ b/doc/en/Makefile.am @@ -0,0 +1,5 @@ +KDE_DOCS = kdiff3 +KDE_LANG = en +man1_MANS=kdiff3.1 + + diff --git a/doc/en/common/appheader.html b/doc/en/common/appheader.html new file mode 100644 index 0000000..8179348 --- /dev/null +++ b/doc/en/common/appheader.html @@ -0,0 +1,36 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <title>$title ($projectname)</title> + <link href="../../common/doxygen.css" rel="stylesheet" type="text/css"> +</head> +<div class="header"> +<table border="0" cellspacing="0" cellpadding="0"> +<tr> +<td rowspan="2" width="92"> +<a href="../../index.html" title="The API documentation main page"><img src="../../common/docheadergears.png" style="border:0px;" alt=""></a> +</td> +<td width="95%"> +<h1>$projectname API Documentation</h1> +</td> +</tr> +<tr> +<td valign="bottom"> +<table class="links" border=0 cellspacing=0> +<tr> +<td><a href="index.html">Overview</a></td> +<td><a href="architecture.html" title="Software architecture and components">Architecture</a></td> +<td><a href="hierarchy.html" title="Inheritance list, sorted roughly alphabetically">Class Hierarchy</a></td> +<td><a href="classes.html" title="Alphabetical list of classes">Classes</a></td> +<td><a href="annotated.html" title="Classes, structs, unions and interfaces with brief descriptions">Classes (annotated)</a></td> +<td><a href="functions.html" title="Documented class members with links to the classes they belong to">Members</a></td> +<td><a href="namespaces.html" title="All documented namespaces with brief descriptions">Namespaces</a></td> +<td><a href="files.html" title="A list of all documented files with brief descriptions">Source Files</a></td> +<td><form action="search.php" method="get"><a title="Search for keywords in the entire documentation">Search for <input type="text" name="query" value="" size="20" accesskey="s"/></a></form></td> +</tr> +</table> +</td></tr></table> +</div> +<div id="hgrad"></div> +<div class="text"> diff --git a/doc/en/common/artistic-license.html b/doc/en/common/artistic-license.html new file mode 100644 index 0000000..2069b4e --- /dev/null +++ b/doc/en/common/artistic-license.html @@ -0,0 +1,165 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html40/strict.dtd"> +<HTML LANG="en-US"> + <HEAD> + <TITLE>The "Artistic License"</TITLE> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii"> + <META HTTP-EQUIV="Content-Language" CONTENT="en-US"> + <META NAME="description" CONTENT="Artistic License"> + <META NAME="keywords" CONTENT="Artistic, artistic, Artistic License, Artistic license, Artisticlicense, artistic license, artisticlicense, Artistic Licence, Artistic licence, Artisticlicence, artistic licence, artisticlicence, license, licence, software, softwarelicense"> + <META NAME="robots" CONTENT="none"> + <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> + <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css"> + </HEAD> + <BODY CLASS="license"> + <H1>The "Artistic License"</H1> + + <H2>Preamble</H2> + + <P>The intent of this document is to state the conditions under + which a Package may be copied, such that the Copyright Holder + maintains some semblance of artistic control over the + development of the package, while giving the users of the + package the right to use and distribute the Package in a + more-or-less customary fashion, plus the right to make + reasonable modifications.</P> + + <H2>Definitions</H2> + + + <P>"Package" refers to the collection of files distributed by the + Copyright Holder, and derivatives of that collection of files + created through textual modification.</P> + + <P>"Standard Version" refers to such a Package if it has not been + modified, or has been modified in accordance with the wishes of + the Copyright Holder as specified below.</P> + + <P>"Copyright Holder" is whoever is named in the copyright or + copyrights for the package.</P> + + <P>"You" is you, if you're thinking about copying or distributing + this Package.</P> + + <P>"Reasonable copying fee" is whatever you can justify on the + basis of media cost, duplication charges, time of people + involved, and so on. (You will not be required to justify it to + the Copyright Holder, but only to the computing community at + large as a market that must bear the fee.)</P> + + <P>"Freely Available" means that no fee is charged for the item + itself, though there may be fees involved in handling the + item. It also means that recipients of the item may redistribute + it under the same conditions they received it.</P> + + + <OL STYLE="list-style-type: decimal;"> + <LI><DIV CLASS="li">You may make and give away verbatim copies of the source + form of the Standard Version of this Package without + restriction, provided that you duplicate all of the original + copyright notices and associated disclaimers.</DIV></LI> + + <LI>You may apply bug fixes, portability fixes and other + modifications derived from the Public Domain or from the + Copyright Holder. A Package modified in such a way shall still + be considered the Standard Version.</LI> + + <LI>You may otherwise modify your copy of this Package in any + way, provided that you insert a prominent notice in each + changed file stating how and when you changed that file, and + provided that you do at least ONE of the following: + <OL STYLE="list-style-type: lower-alpha;"> + <LI>place your modifications in the Public Domain or + otherwise make them Freely Available, such as by posting + said modifications to Usenet or an equivalent medium, or + placing the modifications on a major archive site such as + uunet.uu.net, or by allowing the Copyright Holder to + include your modifications in the Standard Version of the + Package.</LI> + + <LI>use the modified Package only within your corporation or + organization.</LI> + + <LI>rename any non-standard executables so the names do not + conflict with standard executables, which must also be + provided, and provide a separate manual page for each + non-standard executable that clearly documents how it + differs from the Standard Version. d. make other + distribution arrangements with the Copyright Holder.</LI> + </OL> + </LI> + </OL> + + <P>You may distribute the programs of this Package in object code + or executable form, provided that you do at least ONE of the + following:</P> + + <OL STYLE="list-style-type: lower-alpha;"> + <LI>distribute a Standard Version of the executables and library + files, together with instructions (in the manual page or + equivalent) on where to get the Standard Version.</LI> + + <LI>accompany the distribution with the machine-readable source + of the Package with your modifications.</LI> + + <LI>give non-standard executables non-standard names, and + clearly document the differences in manual pages (or + equivalent), together with instructions on where to get the + Standard Version.</LI> + + <LI>make other distribution arrangements with the Copyright + Holder.</LI> + </OL> + + <P>You may charge a reasonable copying fee for any distribution of + this Package. You may charge any fee you choose for support of + this Package. You may not charge a fee for this Package + itself. However, you may distribute this Package in aggregate + with other (possibly commercial) programs as part of a larger + (possibly commercial) software distribution provided that you do + not advertise this Package as a product of your own. You may + embed this Package's interpreter within an executable of yours + (by linking); this shall be construed as a mere form of + aggregation, provided that the complete Standard Version of the + interpreter is so embedded.</P> + + <P>The scripts and library files supplied as input to or produced + as output from the programs of this Package do not automatically + fall under the copyright of this Package, but belong to whomever + generated them, and may be sold commercially, and may be + aggregated with this Package. If such scripts or library files + are aggregated with this Package via the so-called "undump" or + "unexec" methods of producing a binary executable image, then + distribution of such an image shall neither be construed as a + distribution of this Package nor shall it fall under the + restrictions of Paragraphs 3 and 4, provided that you do not + represent such an executable image as a Standard Version of this + Package.</P> + + <P>C subroutines (or comparably compiled subroutines in other + languages) supplied by you and linked into this Package in order + to emulate subroutines and variables of the language defined by + this Package shall not be considered part of this Package, but + are the equivalent of input as in Paragraph 6, provided these + subroutines do not change the language in any way that would + cause it to fail the regression tests for the language.</P> + + <P>Aggregation of this Package with a commercial distribution is + always permitted provided that the use of this Package is + embedded; that is, when no overt attempt is made to make this + Package's interfaces visible to the end user of the commercial + distribution. Such use shall not be construed as a distribution + of this Package.</P> + + <P>The name of the Copyright Holder may not be used to endorse or + promote products derived from this software without specific + prior written permission.</P> + + <P>THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED + WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR + PURPOSE.</P> + + <DIV STYLE="text-align: center;">The End</DIV> + </BODY> +</HTML> diff --git a/doc/en/common/bottom-left.png b/doc/en/common/bottom-left.png Binary files differnew file mode 100644 index 0000000..254e4f8 --- /dev/null +++ b/doc/en/common/bottom-left.png diff --git a/doc/en/common/bottom-middle.png b/doc/en/common/bottom-middle.png Binary files differnew file mode 100644 index 0000000..eddbc9c --- /dev/null +++ b/doc/en/common/bottom-middle.png diff --git a/doc/en/common/bottom-right.png b/doc/en/common/bottom-right.png Binary files differnew file mode 100644 index 0000000..178bf3c --- /dev/null +++ b/doc/en/common/bottom-right.png diff --git a/doc/en/common/fdl-license.html b/doc/en/common/fdl-license.html new file mode 100644 index 0000000..cb1f8a0 --- /dev/null +++ b/doc/en/common/fdl-license.html @@ -0,0 +1,353 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html40/strict.dtd"> +<HTML LANG="en-US"> + <HEAD> + <TITLE>GNU Free Documentation License - version 1.1</TITLE> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii"> + <META HTTP-EQUIV="Content-Language" CONTENT="en-US"> + <META NAME="description" CONTENT="GNU free documentation license (for inclusion in documentation files)"> + <META NAME="keywords" CONTENT="gnu, Gnu, GNU, license, licence, software, free software, software license, software licence, GNU general public license, GNU General Public License, documentation licence, documentation license, documentation, GNU free documentation license, GNU Free Documentation License"> + <META NAME="robots" CONTENT="none"> + <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> + <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css"> + </HEAD> + <BODY CLASS="license"> +<H1>GNU Free Documentation License</H1> + Version 1.1, March 2000 + +<P>Copyright (C) 2000 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA<BR> +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed.</P> + +<H2>0. Preamble</H2> + +<P>The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others.</P> + +<P>This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software.</P> + +<P>We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference.</P> + +<H2>1. Applicability And Definitions</H2> + +<P>This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you".</P> + +<P>A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language.</P> + +<P>A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them.</P> + +<P>The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License.</P> + +<P>The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License.</P> + +<P>A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque".</P> + +<P>Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only.</P> + +<P>The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text.</P> + +<H2>2. Verbatim Copying</H2> + +<P>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3.</P> + +<P>You may also lend copies, under the same conditions stated above, and +you may publicly display copies.</P> + +<H2>3. Copying In Quantity</H2> + +<P>If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects.</P> + +<P>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages.</P> + +<P>If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public.</P> + +<P>It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document.</P> + +<H2>4. Modifications</H2> + +<P>You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version:</P> + +<OL STYLE="list-style-type: upper-alpha;"> +<LI>Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous + version if the original publisher of that version gives + permission.</LI> + +<LI>List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in the + Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, if it has + less than five).</LI> + +<LI>State on the Title page the name of the publisher of the Modified + Version, as the publisher.</LI> + +<LI>Preserve all the copyright notices of the Document.</LI> + +<LI>Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices.</LI> + +<LI>Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum + below.</LI> + +<LI>Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's license + notice.</LI> + +<LI>Include an unaltered copy of this License.</LI> + +<LI>Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence.</LI> + +<LI>Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission.</LI> + +<LI>In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein.</LI> + +<LI>Preserve all the Invariant Sections of the Document, unaltered in + their text and in their titles. Section numbers or the equivalent + are not considered part of the section titles.</LI> + +<LI>Delete any section entitled "Endorsements". Such a section may + not be included in the Modified Version.</LI> + +<LI>Do not retitle any existing section as "Endorsements" or to + conflict in title with any Invariant Section.</LI> +</OL> + +<P>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles.</P> + +<P>You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard.</P> + +<P>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one.</P> + +<P>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version.</P> + +<H2>5. Combining Documents</H2> + +<P>You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice.</P> + +<P>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work.</P> + +<P>In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements."</P> + +<H2>6. Collections Of Documents</H2> + +<P>You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects.</P> + +<P>You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document.</P> + +<H2>7. Aggregation With Independent Works</H2> + +<P>A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document.</P> + +<P>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate.</P> + +<H2>8. Translation</H2> + +<P>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail.</P> + +<H2>9. Termination</H2> + +<P>You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance.</P> + +<H2>10. Future Revisions Of This License</H2> + +<P>The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<A HREF="http:///www.gnu.org/copyleft/">http:///www.gnu.org/copyleft/</A>.</P> + +<P>Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation.</P> + </BODY> +</HTML> diff --git a/doc/en/common/fdl-notice.html b/doc/en/common/fdl-notice.html new file mode 100644 index 0000000..44a1c6c --- /dev/null +++ b/doc/en/common/fdl-notice.html @@ -0,0 +1,15 @@ +<html> +<head> +<title>FDL Notice</title> +</head> + +<body> + +<p>Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or any +later version published by the Free Software Foundation; with no Invariant +Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy +of the license is included <a href="fdl-license.html">here</a>.</p> + +</body> +</html> diff --git a/doc/en/common/footer.html b/doc/en/common/footer.html new file mode 100644 index 0000000..b06dfb8 --- /dev/null +++ b/doc/en/common/footer.html @@ -0,0 +1,65 @@ + </div></div> + + + </td> + </tr> + <tr> + <td valign="top" id="leftmenu" width="25%"> + <a name="navigation"></a> + <div class="menu_box"><h2>$projectname</h2> +<div class="nav_list"> +<!-- menu --> +<!-- cmenu.begin --> +<h2>Class Picker</h2> +<div style="text-align: center;"> +<form name="guideform"> +<select name="guidelinks" style="width:100%;" onChange="window.location=document.guideform.guidelinks.options[document.guideform.guidelinks.selectedIndex].value"> +<option value="annotated.html">-- Choose --</option> +<!-- cmenu --> +</select> +</form> +</div> +<!-- cmenu.end --> +</div></div> +<div class="menu_box"><h2>API Dox</h2> +<div class="nav_list"> +<ul> +<!-- gmenu --> +</ul></div></div> + + + </td> +</tr> +</table> + +<span class="doNotDisplay"> + <a href="http://www.kde.org/" accesskey="8">KDE Home</a> | + <a href="http://accessibility.kde.org/" accesskey="9">KDE Accessibility Home</a> | + <a href="http://www.kde.org/media/accesskeys.php" accesskey="0">Description of Access Keys</a> +</span> + + +<div style="height: 8px"></div> + +<div id="footer"> + <div id="footer_left"> + Maintained by <a href="mailto:groot@kde.org">Adriaan de Groot</a> +and +<a href="mailto:wintert@kde.org">Allen Winter</a>. +<br/> + KDE and K Desktop Environment are trademarks of <a href="http://www.kde.org/areas/kde-ev/" title="Homepage of the KDE non-profit Organization">KDE e.V.</a> | + <a href="http://www.kde.org/contact/impressum.php">Legal</a> + </div> + <div id="footer_right"><img src="/media/images/footer_right.png" style="margin: 0px" alt="" /></div> +</div> + +<!-- +WARNING: DO NOT SEND MAIL TO THE FOLLOWING EMAIL ADDRESS! YOU WILL +BE BLOCKED INSTANTLY AND PERMANENTLY! +<a href="mailto:aaaatrap-425acc3b5374943f@kde.org">Block me</a> +WARNING END +--> + +</body> +</html> + diff --git a/doc/en/common/gpl-license.html b/doc/en/common/gpl-license.html new file mode 100644 index 0000000..26ae3af --- /dev/null +++ b/doc/en/common/gpl-license.html @@ -0,0 +1,381 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html40/strict.dtd"> +<HTML LANG="en-US"> + <HEAD> + <TITLE>GNU General Public License</TITLE> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii"> + <META HTTP-EQUIV="Content-Language" CONTENT="en-US"> + <META NAME="description" CONTENT="GNU general public license (for inclusion in distributions)"> + <META NAME="keywords" CONTENT="gnu, Gnu, GNU, license, licence, software, free software, software license, software licence, GNU general public license, GNU General Public License"> + <META NAME="robots" CONTENT="none"> + <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> + <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css"> + </HEAD> + <BODY CLASS="license"> +<H1>GNU General Public License</H1> +<P>Version 2, June 1991</P> + +<P>Copyright (C) 1989, 1991 Free Software Foundation, Inc. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA<BR> +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed.</P> + +<H2>Preamble</H2> + +<P>The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too.</P> + +<P>When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things.</P> + +<P>To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it.</P> + +<P>For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights.</P> + +<P>We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software.</P> + +<P>Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations.</P> + +<P>Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all.</P> + +<P>The precise terms and conditions for copying, distribution and +modification follow.</P> + +<H2><A NAME="show-c">GNU General Public License<BR> +Terms And Conditions For Copying, Distribution And Modification</A></H2> + +<P>0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you".</P> + +<P>Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does.</P> + +<P>1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program.</P> + +<P>You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee.</P> + +<P>2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions:</P> + +<OL STYLE="list-style-type: lower-alpha;"> +<LI> +<P>You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change.</P> +</LI> + +<LI> +<P>You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License.</P> +</LI> + +<LI> +<P>If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.)</P> +</LI> +</OL> + +<P>These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it.</P> + +<P>Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program.</P> + +<P>In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License.</P> + +<P>3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following:</P> + +<OL STYLE="list-style-type: lower-alpha;"> +<LI> +<P>Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or,</P> +</LI> + +<LI> +<P>Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or,</P> +</LI> + +<LI> +<P>Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.)</P> +</LI> +</OL> + +<P>The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable.</P> + +<P>If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code.</P> + +<P>4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance.</P> + +<P>5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it.</P> + +<P>6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License.</P> + +<P>7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program.</P> + +<P>If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances.</P> + +<P>It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice.</P> + +<P>This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License.</P> + +<P>8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License.</P> + +<P>9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns.</P> + +<P>Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation.</P> + +<P>10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally.</P> + +<H2><A NAME="show-w">No Warranty</A></H2> + +<P>11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION.</P> + +<P>12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES.</P> + +<DIV STYLE="text-align: center;">END OF TERMS AND CONDITIONS</DIV> + +<hr> + +<h2>How to Apply These Terms to Your New Programs</h2> + +<p>If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms.</p> + + +<p>To do so, attach the following notices to the program. It is +safest to attach them to the start of each source file to most +effectively convey the exclusion of warranty; and each file should +have at least the "copyright" line and a pointer to where the full +notice is found.</p> + + +<pre> <one line to give the program's name and a brief idea of what it does.> + Copyright (C) 19yy <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA</pre> + +<p>Also add information on how to contact you by electronic and paper +mail.</p> + +<p>If the program is interactive, make it output a short notice like this +when it starts in an interactive mode:</p> + +<pre> Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details.</pre> + +<p>The hypothetical commands "show w" and "show c" should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than "show w" and "show c"; they could even be +mouse-clicks or menu items--whatever suits your program.</p> + +<p>You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names:</p> + +<pre> Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice</pre> + +<p>This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License.</p> + + + + </BODY> +</HTML> diff --git a/doc/en/common/header.html b/doc/en/common/header.html new file mode 100644 index 0000000..df06da8 --- /dev/null +++ b/doc/en/common/header.html @@ -0,0 +1,56 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US"> + +<head> + <title>$title ($projectname)</title> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <meta http-equiv="Content-Style-Type" content="text/css" /> + + <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" comment "ICRAonline DE v2.0" l gen true for "http://www.kde.org" r (nz 1 vz 1 lz 1 oz 1 cb 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://www.kde.org" r (n 0 s 0 v 0 l 0))' /> + + <meta name="trademark" content="KDE e.V." /> + <meta name="description" content="K Desktop Environment Homepage, KDE.org" /> + <meta name="MSSmartTagsPreventParsing" content="true" /> + <meta name="robots" content="all" /> + + <link rel="shortcut icon" href="@topdir@/favicon.ico" /> + +<link rel="stylesheet" media="screen" type="text/css" title="APIDOX" href="doxygen.css" /> + + + +</head> + +<body> + +<div id="nav_header_top" align="right"> + <a href="#content" class="doNotDisplay" accesskey="2">Skip to main content ::</a> + + <a href="@topdir@"><img id="nav_header_logo" alt="Home" align="left" src="@topdir@/kde_gear_64.png" border="0" /></a> + <span class="doNotDisplay">::</span> + + <div id="nav_header_title" align="left">KDE API Reference</div> + + +</div> + +<div id="nav_header_bottom" align="right"> + <span class="doNotDisplay">:: <a href="#navigation" accesskey="5">Skip to Link Menu</a><br/></span> + <div id="nav_header_bottom_right" style="text-align: left;"> +/ <a href="@topdir@">API Reference</a> +<!-- pmenu $projectname --> + </div> +</div> + + +<table id="main" border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr> + <td valign="top" class="menuheader" height="0"></td> + + <td id="contentcolumn" valign="top" rowspan="2" > + <div id="content" style="padding-top: 0px;"><div style="width:100%; margin: 0px; padding: 0px;"> + <a name="content"></a> + + diff --git a/doc/en/common/headerbg.png b/doc/en/common/headerbg.png Binary files differnew file mode 100644 index 0000000..b72738a --- /dev/null +++ b/doc/en/common/headerbg.png diff --git a/doc/en/common/kde-default.css b/doc/en/common/kde-default.css new file mode 100644 index 0000000..35e9d4d --- /dev/null +++ b/doc/en/common/kde-default.css @@ -0,0 +1,327 @@ +/* + KDE-wide default CSS for HTML documentation (all media types). + Copyright (C) 2000 Frederik Fouvry + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Send comments, suggestions, etc. to Frederik Fouvry + <fouvry@sfs.nphil.uni-tuebingen.de>. */ + +/* + Important note: these setting may be overridden by localised CSS. Do not + add here any localization-sensitive style declarations. + + Any updates should be validated, e.g. http://jigsaw.w3.org/css-validator/ */ + +/* Note: "should be inherit" means that in a proper browser inherit should work. + Somehow Netscape manages to interpret "inherit" as bright green. + Yuck. */ + +body { + background: white none; + color: black; + font-family: sans-serif; + padding: 0; + margin: 0; +} + +.legalnotice, .copyright { + padding: 0; + margin: 0; +} + +.abstract { + font-weight: bolder; + padding-right: 1em; +} + +.toc, .list-of-tables { + padding-left: 1em; +} + +.sect1, .chapter, .synopsis, .appendix, .preface, .article, .refsect1, .index, .glossary, .section { + padding: 1em; +} + +.toc .chapter { +padding: 0em 0em 0em 1em; +} + +.author { + color: rgb(82,80,82); + font-weight: bolder; + padding: 0; + margin: 0; +} + +.othercredit { + line-height: 1em; +} + +.chapter .sect1, .chapter .titlepage, .sect1 .titlepage, .article .titlepage { + padding: 0em; +} + +.titlepage { + padding-left: 1em; + padding-right: 1em; +} + +/* Links in Navigation */ + +.navLeft a:link, .navCenter a:link, .navRight a:link, .header a:link, .header a:visited, .bottom-nav a:link, .bottom-nav a:visited { + color: #41597A; + font-weight: bold; +} + + +/* Nice link colors for the main text */ + +:link { + color: #41597A; +} + +:visited { + color: #597ba8; +} + +.navLeft { + position: absolute; + left: 20px; +} + +.navRight { + position: absolute; + right: 20px; +} + +.navCenter { + text-align: center; + align: center; +} + +.bannerBottomLeft { + position: absolute; left: 0px; +} + +.bannerBottomRight { + position: absolute; right: 0px; +} + +.header { + background: #3E91EB none; + border-bottom: 1px solid #206dcd; + border-top: 1px solid white; + color: white; + font-size: small; + height: 1.7em; + line-height: 1em; + margin: 0px; + padding-bottom: 0px; + padding-left: 1em; + padding-right: 0px; + padding-top: 0px; + vertical-align: middle; +} + +.bottom-nav { + background-color: #3E91EB; + border-bottom: 1px solid #206dcd; + border-top: 1px solid white; + color: white; + font-size: small; + height: 1.7em; + line-height: 1em; + margin: 0px; + padding-bottom: 0px; + padding-left: 1em; + padding-right: 0px; + padding-top: 10px; + vertical-align: middle; +} + +#logo { + background: url('kde_logo_bg.png') transparent repeat; +} + +/* A little bit of padding makes the tables for keybindings etc much easier to read */ + +table { + padding: 5px; +} + +dl { + margin-top: 0em; + margin-bottom: 0.5em; +} + +dt { + margin-top: 1em; +} +div.toc dt { + margin-top: 0px; +} +div.screenshot { + margin-bottom: 1em; + margin-top: 1em; +} + +div.informalexample { + border-style: dotted; + padding: 10px; +} + +/* But no padding for navigation elements */ + +.toplogo, .navbackground { + padding: 0px; +} + +table.programlisting +table.screen { + border-style: none; + background-color: rgb(224,224,224); + table-layout: auto; /* 100%? */ + color: rgb(0,0,0); /* should be inherit */ +} + +/* Same as previous block, but more general (previous is HTML only) + Not all browsers understand this yet. + TABLE[class~=programlisting] + TABLE[class~=screen] { border-style: none; + background-color: rgb(224,224,224); + table-layout: auto; + color: inherit; +} +*/ + +p { + text-align: justify; +} + +/* More specific settings */ +/* Temporary patch: browsers break on bad HTML */ +/* P, H1, H2, H3, H4, H5, TD, TH { font-family: Helvetica, Arial, sans-serif; + } */ + +p, h1, h2, h3, h4, h5, h6, td, th { + font-family: sans-serif; +} + +/* Visual cues for GUI elements etc in the text */ + +.guimenu, .guimenuitem, .guisubmenu { + background-color: rgb(250,250,250); + color: rgb(0,0,0); /* should be inherit */ +} + +.guilabel, .interface, .guibutton { + background-color: rgb(250,250,250); + color: rgb(0,0,0); /* should be inherit */ +} + +.shortcut { + background-color: rgb(250,250,250); + color: rgb(0,0,0); /* should be inherit */ +} + +.shortcut .keycap { + background-color: rgb(250,250,250); + color: rgb(0,0,0); /* should be inherit */ +} + +.question { + font-weight: bolder; +} + +.accel { + background-color: rgb(250,250,250); + color: rgb(0,0,0); + text-decoration: underline; +} + +.option, .command { + background-color: rgb(255,255,255); + color: rgb(0,96,160); + font-weight: bold; +} + +h1, h2, h3, h4, h5, h6 { + color: rgb(82,80,82); + background-color: transparent; +} + +.arg, .parameter, .replaceable { + background-color: rgb(255,255,255); + color: rgb(0,128,64); + font-style: italic; +} + +.screen, .programlisting { + background-color: rgb(250,250,250); + color: rgb(0,0,0); /* should be inherit */ + border-style: dotted; + border-color: rgb(0,0,0); + border-width: thin; + padding: 5px; +} + + +/* This one is set in inches because the admonitions are set in inches + and they're more difficult to change. We can live with it in here, + for the meantime, it gives consistent margins */ + +.example { + margin-left: 0.5in; + margin-right: 0.5in; +} + +div.mediaobject { + /* float: right; */ + /* might make it much nicer. although someone has to + understand the rules ;-) You also don't want it to be + surrounded by text it doesn't refer to ... But that + may be among others a question of writing style. */ + text-align: center; /* a bit of a hack: it should + position _images_ */ +} + +.caption { + margin: 0em 2em 3em 2em; + text-align: center; +} + +.inlinemediaobject { + vertical-align: baseline; + padding-right: 1em; + padding-left: 1em; +} + +/* An idea that could be nice: a search engine looking for specific +classes could display them in some conspicuous color. All that is +needed is an on the fly generated style element/style sheet. */ + +/* Only used in the hand-made HTML license texts */ +body.license { + background-color: rgb(255,255,255); + text-align: justify; + color: rgb(0,0,0); +} +pre.license { + background-color: rgb(255,255,255); + font-family: monospace; + color: rgb(0,0,0); +} + diff --git a/doc/en/common/kde-localised.css.template b/doc/en/common/kde-localised.css.template new file mode 100644 index 0000000..abcd1ec --- /dev/null +++ b/doc/en/common/kde-localised.css.template @@ -0,0 +1,32 @@ +/* + KDE CSS for <**languagecountry**> HTML documentation (all media types). + Copyright (C) 2000 <**authorname**> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Send comments, suggestions, etc. to <**authorcontactdetails**>. +*/ + +/* + These settings will override kde-default.css. + + Any updates should be validated, e.g. http://jigsaw.w3.org/css-validator/ + + Check out http://www.richinstyle.com/ where many of the declarations and + setup in the KDE CSS are obtained from. In fact, do not change anything + without checking so on those pages whether it is wise to do. +*/ + +:lg(**language**) { } diff --git a/doc/en/common/kde_gear_64.png b/doc/en/common/kde_gear_64.png Binary files differnew file mode 100644 index 0000000..ee74c3b --- /dev/null +++ b/doc/en/common/kde_gear_64.png diff --git a/doc/en/common/kde_logo_bg.png b/doc/en/common/kde_logo_bg.png Binary files differnew file mode 100644 index 0000000..5ab7542 --- /dev/null +++ b/doc/en/common/kde_logo_bg.png diff --git a/doc/en/common/mainfooter.html b/doc/en/common/mainfooter.html new file mode 100644 index 0000000..a2d753e --- /dev/null +++ b/doc/en/common/mainfooter.html @@ -0,0 +1,68 @@ + </div></div> + + + </td> + </tr> + <tr> + <td valign="top" id="leftmenu" width="25%"> + <a name="navigation"></a> +<div class="menu_box"><h2>API Dox</h2> +<div class="nav_list"> +<ul> +<!-- gmenu --> +</ul></div></div> + + + </td> +</tr> +</table> + +<div class="copyrights"> +This file is part of the documentation for $projectname $projectnumber.<br/> +Documentation copyright © 1996-2005 the KDE developers.<br/> +Generated on $datetime by +<a href="http://www.doxygen.org/index.html">doxygen</a> $doxygenversion written +by <a href="mailto:dimitri@stack.nl">Dimitri van Heesch</a>, © 1997-2003 +<p> +KDE's <a href="http://developer.kde.org/policies/documentationpolicy.html">Doxygen guidelines</a> are available online. +Questions about the reference manuals should be sent to +<a href="mailto:groot@kde.org">Adriaan de Groot</a> +or +<a href="mailto:wintert@kde.org">Allen Winter</a>. +</p> +</div> + +<div style="clear:both; height: 1px;"> </div> + + +<span class="doNotDisplay"> + <a href="http://www.kde.org/" accesskey="8">KDE Home</a> | + <a href="http://accessibility.kde.org/" accesskey="9">KDE Accessibility Home</a> | + <a href="http://www.kde.org/media/accesskeys.php" accesskey="0">Description of Access Keys</a> +</span> + + +<div style="height: 8px"></div> + +<div id="footer"> + <div id="footer_left"> + Maintained by <a href="mailto:groott@kde.org>Adriaan de Groot</a> + and +<a href="mailto:wintert@kde.org">Allen Winter</a>. +<br/> + KDE and K Desktop Environment are trademarks of <a href="http://www.kde.org/areas/kde-ev/" title="Homepage of the KDE non-profit Organization">KDE e.V.</a> | + <a href="http://www.kde.org/contact/impressum.php">Legal</a> + </div> + <div id="footer_right"><img src="/media/images/footer_right.png" style="margin: 0px" alt="" /></div> +</div> + +<!-- +WARNING: DO NOT SEND MAIL TO THE FOLLOWING EMAIL ADDRESS! YOU WILL +BE BLOCKED INSTANTLY AND PERMANENTLY! +<a href="mailto:aaaatrap-425acc3b5374943f@kde.org">Block me</a> +WARNING END +--> + +</body> +</html> + diff --git a/doc/en/common/mainheader.html b/doc/en/common/mainheader.html new file mode 100644 index 0000000..4ea02fe --- /dev/null +++ b/doc/en/common/mainheader.html @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US"> + +<head> + <title>$projectname</title> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <meta http-equiv="Content-Style-Type" content="text/css" /> + + <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" comment "ICRAonline DE v2.0" l gen true for "http://www.kde.org" r (nz 1 vz 1 lz 1 oz 1 cb 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://www.kde.org" r (n 0 s 0 v 0 l 0))' /> + + <meta name="trademark" content="KDE e.V." /> + <meta name="description" content="K Desktop Environment Homepage, KDE.org" /> + <meta name="MSSmartTagsPreventParsing" content="true" /> + <meta name="robots" content="all" /> + + <link rel="shortcut icon" href="@topdir@/favicon.ico" /> + +<link rel="stylesheet" media="screen" type="text/css" title="APIDOX" href="doxygen.css" /> + + +<style type="text/css"> +<!-- +hr { display: none; } +#content h2 { margin-left: 0px; } +table.mdTable { background-color: #f8f8f8; border: .2em solid #d7d7d7; } +td.mdRow { padding: 8px 20px; } +td.md { font-weight: bold; } +td.mdname1 { font-weight: bold; color: #602020; } +td.mdname { font-weight: bold; color: #602020; } + +.copyrights { width: 80%; margin: 1ex 10%; color:#BCBCBC; } +.copyrights a { color: #9A9A9A; } + +--> +</style> + +</head> + +<body> + +<div id="nav_header_top" align="right"> + <a href="#content" class="doNotDisplay" accesskey="2">Skip to main content ::</a> + + <a href="@topdir@"><img id="nav_header_logo" alt="Home" align="left" src="@topdir@/kde_gear_64.png" border="0" /></a> + <span class="doNotDisplay">::</span> + + <div id="nav_header_title" align="left">KDE API Reference</div> + + +</div> + +<div id="nav_header_bottom" align="right"> + <span class="doNotDisplay">:: <a href="#navigation" accesskey="5">Skip to Link Menu</a><br/></span> + <div id="nav_header_bottom_right" style="text-align: left;"> +/ <a href="@topdir@">API Reference</a> + </div> +</div> + + +<table id="main" border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr> + <td valign="top" class="menuheader" height="0"></td> + + <td id="contentcolumn" valign="top" rowspan="2" > + <div id="content"><div style="width:100%;"> + <a name="content"></a> + + diff --git a/doc/en/common/top-left.png b/doc/en/common/top-left.png Binary files differnew file mode 100644 index 0000000..95f055d --- /dev/null +++ b/doc/en/common/top-left.png diff --git a/doc/en/common/top-middle.png b/doc/en/common/top-middle.png Binary files differnew file mode 100644 index 0000000..fbebf6a --- /dev/null +++ b/doc/en/common/top-middle.png diff --git a/doc/en/common/top-right-konqueror.png b/doc/en/common/top-right-konqueror.png Binary files differnew file mode 100644 index 0000000..ca1d974 --- /dev/null +++ b/doc/en/common/top-right-konqueror.png diff --git a/doc/en/compilation.html b/doc/en/compilation.html new file mode 100644 index 0000000..9974fea --- /dev/null +++ b/doc/en/compilation.html @@ -0,0 +1,11 @@ +<html><head><title>Compilation and Installation</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="installation.html" title="Appendix A. Installation"><link rel="prev" href="requirements.html" title="Requirements"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Compilation and Installation</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="requirements.html">Prev</a></div><div style="position: absolute; right: 20px;"></div><div class="navCenter">Installation</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="compilation"></a>Compilation and Installation</h2></div></div></div><p>In order to compile and install <span class="application">KDiff3</span> on a system with KDE, type the +following in the base directory of the <span class="application">KDiff3</span> distribution:</p><pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">./configure --prefix=<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>kde-dir</code></em></span></strong></span></span></code></strong> +<code class="prompt">%</code> <strong class="userinput"><code><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">make</strong></span></span></code></strong> +<code class="prompt">%</code> <strong class="userinput"><code><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">make</strong></span></span> install</code></strong> +</pre><p> +<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>kde-dir</code></em></span> specifies the directory +containing KDE on your system. If you are not sure, read the README-file for details. +</p><p>If you don't use KDE don't use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">configure</strong></span></span> but follow the instructions for Qt-only systems in the README file.</p><p>Since <span class="application">KDiff3</span> uses <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">autoconf</strong></span></span> and +<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">automake</strong></span></span> you should have no trouble compiling it. Should you +run into problems please report them to the <span class="acronym">KDE</span> mailing lists.</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="requirements.html">Prev</a></div><div style="position: absolute; right: 20px;"></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Requirements </div><div class="navRight"> </div><div class="navCenter"><a accesskey="u" href="installation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/credits.html b/doc/en/credits.html new file mode 100644 index 0000000..ceb4d5b --- /dev/null +++ b/doc/en/credits.html @@ -0,0 +1,11 @@ +<html><head><title>Chapter 6. Credits and License</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="index.html" title="The KDiff3 Handbook"><link rel="prev" href="faq.html" title="Chapter 5. Questions and Answers"><link rel="next" href="installation.html" title="Appendix A. Installation"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Credits and License</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="faq.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="installation.html">Next</a></div><div class="navCenter"> </div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="credits"></a>Chapter 6. Credits and License</h2></div></div></div><p> +<span class="application">KDiff3</span> - File and Directory Comparison and Merge Tool +</p><p> +Program copyright 2002-2007 Joachim Eibl <code class="email">(joachim.eibl at gmx.de)</code> +</p><p> +Several cool ideas and bugreports came from colleagues and many people out in the Wild Wild Web. Thank you! +</p><p> +Documentation Copyright (c) 2002-2007 Joachim Eibl <code class="email">(joachim.eibl at gmx.de)</code> +</p><p><a name="gnu-fdl"></a>This documentation is licensed under the terms of the <a href="common/fdl-license.html" target="_top">GNU Free Documentation +License</a>.</p><p>This program is licensed under the terms of the <a href="common/gpl-license.html" target="_top">GNU General Public License</a>.</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="faq.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="installation.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Questions and Answers </div><div class="navRight"> Installation</div><div class="navCenter"><a accesskey="u" href="index.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/dirbrowser.png b/doc/en/dirbrowser.png Binary files differnew file mode 100644 index 0000000..d3c63b2 --- /dev/null +++ b/doc/en/dirbrowser.png diff --git a/doc/en/dirmerge.html b/doc/en/dirmerge.html new file mode 100644 index 0000000..f83a481 --- /dev/null +++ b/doc/en/dirmerge.html @@ -0,0 +1,25 @@ +<html><head><title>Chapter 3. Directory Comparison and Merge with KDiff3</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="index.html" title="The KDiff3 Handbook"><link rel="prev" href="preprocessors.html" title="Preprocessor Commands"><link rel="next" href="startingdirmerge.html" title="Starting Directory Comparison Or Merge"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Directory Comparison and Merge with <span class="application">KDiff3</span></div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="preprocessors.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="startingdirmerge.html">Next</a></div><div class="navCenter"> </div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="dirmerge"></a>Chapter 3. Directory Comparison and Merge with <span class="application">KDiff3</span></h2></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dirmergeintro"></a>Introduction into Directory Comparison and Merge</h2></div></div></div><p> + Often programmers must modify many files in a directory to achieve their + purpose. For this <span class="application">KDiff3</span> also lets you compare and merge complete directories + recursively! +</p><p> + 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 <span class="application">KDiff3</span>) 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: +</p><div class="blockquote"><blockquote class="blockquote"><p> + <span class="emphasis"><em>To err is human, but to really mess things up you need a computer.</em></span> +</p></blockquote></div><p> +So this is what this program can do for you: <span class="application">KDiff3</span> ... +</p><div class="itemizedlist"><ul type="disc"><li><p>... reads and compares two or three directories recursively,</p></li><li><p>... takes special care of symbolic links,</p></li><li><p>... lets you browse files on mouse double click,</p></li><li><p>... for each item proposes a merge operation, which you can change + before starting the directory merge,</p></li><li><p>... lets you simulate the merge and lists the actions that would + take place, without actually doing them,</p></li><li><p>... lets you really do the merge, and lets you interact whenever + manual interaction is needed,</p></li><li><p>... lets you run the selected operation for all items (key F7) or the selected item (key F6),</p></li><li><p>... lets you continue the merge after manual interaction with key F7,</p></li><li><p>... optionally creates backups, with the ".orig" extension,</p></li><li><p>...</p></li></ul></div></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="preprocessors.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="startingdirmerge.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Preprocessor Commands </div><div class="navRight"> Starting Directory Comparison Or Merge</div><div class="navCenter"><a accesskey="u" href="index.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/dirmergebig.png b/doc/en/dirmergebig.png Binary files differnew file mode 100644 index 0000000..b26b65c --- /dev/null +++ b/doc/en/dirmergebig.png diff --git a/doc/en/dirmergeoptions.html b/doc/en/dirmergeoptions.html new file mode 100644 index 0000000..9d126b3 --- /dev/null +++ b/doc/en/dirmergeoptions.html @@ -0,0 +1,58 @@ +<html><head><title>Options for Comparing and Merging Directories</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3"><link rel="prev" href="dothemerge.html" title="Doing A Directory Merge"><link rel="next" href="other.html" title="Other Functions in Directory Merge Window"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Options for Comparing and Merging Directories</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="dothemerge.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="other.html">Next</a></div><div class="navCenter">Directory Comparison and Merge with <span class="application">KDiff3</span></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dirmergeoptions"></a>Options for Comparing and Merging Directories</h2></div></div></div><p> + The <span class="application">KDiff3</span>-preferences (menu "Settings"->"Configure <span class="application">KDiff3</span>") has + a section called "Directory Merge" with these options: +</p><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Recursive Directories:</em></span></span></dt><dd><p> Select whether to search directories + recursively.</p></dd><dt><span class="term"><span class="emphasis"><em>File Pattern(s):</em></span></span></dt><dd><p> Only files that match any pattern here will + be put in the tree. More than one pattern may be specified here by using + the semicolon ";" as separator. Valid wildcards: '*' and '?'. (e.g. "*.cpp;*.h"). + Default is "*". This pattern is not used on directories.</p></dd><dt><span class="term"><span class="emphasis"><em>File Anti-Pattern(s):</em></span></span></dt><dd><p> Files 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;*.obj".</p></dd><dt><span class="term"><span class="emphasis"><em>Directory Anti-Pattern(s):</em></span></span></dt><dd><p> 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 "CVS;deps;.svn".</p></dd><dt><span class="term"><span class="emphasis"><em>Use CVS-Ignore:</em></span></span></dt><dd><p> + 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 <a href="info:/cvs/cvsignore" target="_top">info:/cvs/cvsignore</a>.)</p></dd><dt><span class="term"><span class="emphasis"><em>Find Hidden Files and Directories:</em></span></span></dt><dd><p> On some file systems 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.</p></dd><dt><span class="term"><span class="emphasis"><em>Follow File Links:</em></span></span></dt><dd><p> 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.</p></dd><dt><span class="term"><span class="emphasis"><em>Follow Directory Links:</em></span></span></dt><dd><p> 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.</p></dd><dt><span class="term"><span class="emphasis"><em>Case Sensitive Filename Comparison:</em></span></span></dt><dd><p> + Default is false on Windows, true for other operating systems.</p></dd><dt><span class="term"><span class="emphasis"><em>File Comparison Mode:</em></span></span></dt><dd><p> +<div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Binary Comparison:</em></span></span></dt><dd><p> + This is the default file comparison mode. + </p></dd><dt><span class="term"><span class="emphasis"><em>Full Analysis:</em></span></span></dt><dd><p> + Do a full analysis of each file and show the statistics information columns. + (Number of solved, unsolved, nonwhite and white conflicts.) + The full analysis is slower than a simple binary analysis, and much + slower when used on files that don't contain text. + (Specify the appropriate file-antipatterns.) + </p></dd><dt><span class="term"><span class="emphasis"><em>Trust the modification date:</em></span></span></dt><dd><p> 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.</p></dd><dt><span class="term"><span class="emphasis"><em>Trust the size:</em></span></span></dt><dd><p> + Similar to trusting the modification date. No real comparison happens. Two + files are considered equal if their file-sizes are equal. This is useful + when the file-copy operation didn't preserve the modification date. + Use this option with care. Default is off.</p></dd></dl></div></p></dd><dt><span class="term"><span class="emphasis"><em>Synchronize Directories:</em></span></span></dt><dd><p> 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.</p></dd><dt><span class="term"><span class="emphasis"><em>Copy newer instead of merging:</em></span></span></dt><dd><p> Instead of merging the proposed + operation will copy the newer source if changes happened. (Considered unsafe, + because it implies that you know, that the other file hasn't been edited + too. Check to make sure in every case.) Default is off.</p></dd><dt><span class="term"><span class="emphasis"><em>Backup files:</em></span></span></dt><dd><p> 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.</p></dd></dl></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="dothemerge.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="other.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Doing A Directory Merge </div><div class="navRight"> Other Functions in Directory Merge Window</div><div class="navCenter"><a accesskey="u" href="dirmerge.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/dirmergevisible.html b/doc/en/dirmergevisible.html new file mode 100644 index 0000000..fd20589 --- /dev/null +++ b/doc/en/dirmergevisible.html @@ -0,0 +1,105 @@ +<html><head><title>Directory Merge Visible Information</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3"><link rel="prev" href="startingdirmerge.html" title="Starting Directory Comparison Or Merge"><link rel="next" href="dothemerge.html" title="Doing A Directory Merge"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Directory Merge Visible Information</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="startingdirmerge.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dothemerge.html">Next</a></div><div class="navCenter">Directory Comparison and Merge with <span class="application">KDiff3</span></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dirmergevisible"></a>Directory Merge Visible Information</h2></div></div></div><p> + 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. +</p><p> + When the directory scan is complete then <span class="application">KDiff3</span> will show a listbox with + the results left, ... +</p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="dirbrowser.png"><hr></div></div><p> + ... and details about the currently selected item on the right: +</p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="iteminfo.png"><hr></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="name"></a>The Name Column</h3></div></div></div><p> + 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. +</p><p> + 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. +</p><p> + If you double-click a file item then the file comparison starts and the + file-diff-window will appear. +</p><p> + The image in the name column reflects the file type in the first + directory ("A"). It can be one of these: +</p><div class="itemizedlist"><ul type="disc"><li><p>Normal file</p></li><li><p>Normal directory (directory-image)</p></li><li><p>Link to a file (file-image with a link arrow)</p></li><li><p>Link to a directory (directory-image with a link arrow)</p></li></ul></div><p> + 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="coloring"></a>The Columns A/B/C and the Coloring Scheme</h3></div></div></div><p> + As can be seen in the image above the colors red, green, yellow and black + are used in the columns A/B/C. +</p><div class="itemizedlist"><ul type="disc"><li><p>Black: This item doesn't exist in this directory.</p></li><li><p>Green: Newest item.</p></li><li><p>Yellow: Older than green, newer than red.</p></li><li><p>Red: Oldest item.</p></li></ul></div><p> + But for items that were identical in the comparison their color also is + identical even if the age is not. +</p><p> + 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. +</p><p> + The idea for this coloring scheme I came upon in + <a href="http://samba.org/cgi-bin/cvsweb/dirdiff" target="_top">dirdiff</a>. The colors + resemble the colors of a leaf that is green when new, turns yellow later and red + when old. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="operation"></a>The Operation Column</h3></div></div></div><p> + After comparing the directories <span class="application">KDiff3</span> 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. (You can also + select the most needed operations via keyboard. + Ctrl+1/2/3/4/Del will select A/B/C/Merge/Delete respectively if available.) + 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 +</p><div class="itemizedlist"><ul type="disc"><li><p>Three directory-merge ("A" is treated as older base of both).</p></li><li><p>Two directory-merge.</p></li><li><p>Two directory-sync-mode (activate via option "Synchronize Directories").</p></li></ul></div><p> + In three directory merge the operation proposal will be: If for an item ... +</p><div class="itemizedlist"><ul type="disc"><li><p>... all three directories are equal: Copy from C</p></li><li><p>... A and C are equal but B is not: Copy from B (or if B does not + exist, delete the destination if exists)</p></li><li><p>... A and B are equal but C is not: Copy from C (or if C does not + exist, delete the destination if exists)</p></li><li><p>... B and C are equal but A is not: Copy from C (or if C does not + exist, delete the destination if exists)</p></li><li><p>... only A exists: Delete the destination (if exists)</p></li><li><p>... only B exists: Copy from B</p></li><li><p>... only C exists: Copy from C</p></li><li><p>... A, B and C are not equal: Merge</p></li><li><p>... 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.</p></li></ul></div><p> + In two directory merge the operation proposal will be: If for an item ... +</p><div class="itemizedlist"><ul type="disc"><li><p>... both directories are equal: Copy from B</p></li><li><p>... A exists, but not B: Copy from A</p></li><li><p>... B exists, but not A: Copy from B</p></li><li><p>... A and B exist but are not equal: Merge</p></li><li><p>... 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.</p></li></ul></div><p> + Sync-mode is active if only two directories and no explicit destination + were specified and if the option "Synchronize directories" is active. <span class="application">KDiff3</span> + then selects a default operation so that both directories are the same afterwards. + If for an item ... +</p><div class="itemizedlist"><ul type="disc"><li><p>... both directories are equal: Nothing will be done.</p></li><li><p>... A exists, but not B: Copy A to B</p></li><li><p>... B exists, but not A: Copy B to A</p></li><li><p>... 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 <span class="application">KDiff3</span> copies B also to A.)</p></li><li><p>... 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.</p></li></ul></div><p> + When two directories are merged and the option "Copy newer instead of merging" is selected, + then <span class="application">KDiff3</span> 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="status"></a>The Status Column</h3></div></div></div><p> + 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="statisticscolulmns"></a>Statistics Columns</h3></div></div></div><p> + When the file comparison mode "Full Analysis" is enabled in the options, then + <span class="application">KDiff3</span> will show extra columns containing the numbers of unsolved, solved, nonwhite and whitespace + conflicts. (The solved-column will only show when comparing or merging three directories.) +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="selectingvisiblefiles"></a>Selecting Listed Files</h3></div></div></div><p> + Several options influence which files are listed here. Some are accessible in the + <a href="dirmergeoptions.html" title="Options for Comparing and Merging Directories">settings dialog</a>. The Directory-menu contains the entries: +</p><p><div class="itemizedlist"><ul type="disc"><li><p>"Show Identical Files": Files that have been detected equal in all input directories.</p></li><li><p>"Show Different Files": Files that exist in two or more directories but are not equal.</p></li><li><p>"Show Files only in A": Files that exist only in A, but not in B or C.</p></li><li><p>"Show Files only in B": Files that exist only in B, but not in A or B.</p></li><li><p>"Show Files only in C": Files that exist only in C, but not in A or B.</p></li></ul></div></p><p> + Activate only the "Show"-options for the items you want listed. If for example you only want to list all items that + exist either in A or in B but not in both, you'll have to activate "Show Files only in A" and "Show Files only in B" + and deactivate all others ("Show Identical Files", "Show Different Files", "Show Files only in C"). + The list will be updated immediately to reflect the change. +</p><p> + These options also apply for directories with one exception: Disabling "Show Different Files" will not hide + any complete directories. This will work only for files within. +</p><p> + Note that of these only the "Show Identical Files"-option is persistant. The others are enabled when starting <span class="application">KDiff3</span>. +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="startingdirmerge.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dothemerge.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Starting Directory Comparison Or Merge </div><div class="navRight"> Doing A Directory Merge</div><div class="navCenter"><a accesskey="u" href="dirmerge.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/documentation.html b/doc/en/documentation.html new file mode 100644 index 0000000..9a0ebd6 --- /dev/null +++ b/doc/en/documentation.html @@ -0,0 +1,54 @@ +<html><head><title>Chapter 2. File Comparison And Merge</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="index.html" title="The KDiff3 Handbook"><link rel="prev" href="features.html" title="More Features"><link rel="next" href="opendialog.html" title="Open-Dialog"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">File Comparison And Merge</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="features.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="opendialog.html">Next</a></div><div class="navCenter"> </div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="documentation"></a>Chapter 2. File Comparison And Merge</h2></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="commandline"></a>Command-Line Options</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2488302"></a>Comparing 2 files: </h3></div></div></div><pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file1 file2</code></em></span> +</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2488321"></a>Merging 2 files: </h3></div></div></div><pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file1 file2</code></em></span> -m + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file1 file2</code></em></span> -o <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>outputfile</code></em></span> +</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2488352"></a>Comparing 3 files: </h3></div></div></div><pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file1 file2 file3</code></em></span> +</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2488370"></a>Merging 3 files: </h3></div></div></div><pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file1 file2 file3</code></em></span> -m + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file1 file2 file3</code></em></span> -o <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>outputfile</code></em></span> +</pre><p> + Note that <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file1</code></em></span> will be treated as + base of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file2</code></em></span> and + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>file3</code></em></span>. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2488418"></a>Special case: Files with the same name </h3></div></div></div><p> +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.: +</p><pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1/filename dir2 dir3</code></em></span> +</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2488444"></a>Commandline for starting a directory comparison or merge: </h3></div></div></div><p>This is very similar, but now it's about directories.</p><pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1 dir2</code></em></span> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1 dir2</code></em></span> -o <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>destdir</code></em></span> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1 dir2 dir3</code></em></span> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1 dir2 dir3</code></em></span> -o <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>destdir</code></em></span> +</pre><p>For directory comparison and merge you can continue to read <a href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3">here</a>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2488514"></a>Other command line options</h3></div></div></div><p>To see all available command line options type</p><pre class="screen"> +<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> --help +</pre><p>Example output:</p><pre class="screen"> +Options: + -m, --merge Merge the input. + -b, --base file Explicit base file. For compatibility with certain tools. + -o, --output file Output file. Implies -m. E.g.: -o newfile.txt + --out file Output file, again. (For compatibility with certain tools.) + --auto No GUI if all conflicts are auto-solvable. (Needs -o file) + --qall Don't solve conflicts automatically. (For compatibility...) + --L1 alias1 Visible name replacement for input file 1 (base). + --L2 alias2 Visible name replacement for input file 2. + --L3 alias3 Visible name replacement for input file 3. + -L, --fname alias Alternative visible name replacement. Supply this once for every input. + --cs string Override a config setting. Use once for every setting. E.g.: --cs "AutoAdvance=1" + --confighelp Show list of config settings and current values. + --config file Use a different config file. +</pre><p>The option <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="option"><code class="option">--cs</code></span> allows you to adjust a configuration value that is otherwise only adjustable via the configure dialogs. +But be aware that when <span class="application">KDiff3</span> then terminates the changed value will be stored along with the other settings. +With <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="option"><code class="option">--confighelp</code></span> you can find out the names of the available items and current values.</p><p>Via <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="option"><code class="option">--config</code></span> you can specify a different config file. When you often use <span class="application">KDiff3</span> +with completely different setups this allows you to easily switch between them.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2488593"></a>Ignorable command line options</h3></div></div></div><p>Many people want to use <span class="application">KDiff3</span> with some version control system. +But when that version control system calls <span class="application">KDiff3</span> using command line parameters that <span class="application">KDiff3</span> doesn't recognise, then <span class="application">KDiff3</span> terminates with an error. +The integration settings allow to specify command line parameters that should be ignored by <span class="application">KDiff3</span>. +They will appear in the usage help like in this example:</p><pre class="screen"> + --<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>foo</code></em></span> Ignored. (User defined.) +</pre><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Command line options to ignore:</em></span></span></dt><dd><p> + A list of options, separated via semicolon ';'. When one of these options appears on the commandline, + then <span class="application">KDiff3</span> will ignore it and run without reporting an error. + (Default is "u;query;html;abort").</p></dd></dl></div><p>When this isn't enough, then it is recommended to write a shell script that does the option translation.</p></div></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="features.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="opendialog.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">More Features </div><div class="navRight"> Open-Dialog</div><div class="navCenter"><a accesskey="u" href="index.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/dothemerge.html b/doc/en/dothemerge.html new file mode 100644 index 0000000..1bf4d11 --- /dev/null +++ b/doc/en/dothemerge.html @@ -0,0 +1,65 @@ +<html><head><title>Doing A Directory Merge</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3"><link rel="prev" href="dirmergevisible.html" title="Directory Merge Visible Information"><link rel="next" href="dirmergeoptions.html" title="Options for Comparing and Merging Directories"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Doing A Directory Merge</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="dirmergevisible.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dirmergeoptions.html">Next</a></div><div class="navCenter">Directory Comparison and Merge with <span class="application">KDiff3</span></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dothemerge"></a>Doing A Directory Merge</h2></div></div></div><p> + You can either merge the currently selected item (file or directory), or all items. + When you have made all your operation choices (in all subdirectories too) + then you can start the merge. +</p><p> + 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". +</p><p> + 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: +</p><div class="itemizedlist"><ul type="disc"><li><p>"Recursive Directories": If this is off, then items in subdirectories + will not be found.</p></li><li><p>"Pattern"/"Anti-Pattern": Include/exclude items that match</p></li><li><p>"Exclude Hidden Files"</p></li><li><p><a href="dirmergevisible.html#selectingvisiblefiles" title="Selecting Listed Files">"Show"-options</a> (Show Identical/Different Files, Files only in A/B/C)</p></li></ul></div><p> + If you change the settings in order to list more files, you must do a rescan via menu "Directory"->"Rescan" yourself. + (The reason for this is that for faster comparison-speed <span class="application">KDiff3</span> omits the comparison for files suppressed by these criteria.) + If you changed your file and dir patterns to exclude files, then the file-list will immediately be updated on closing + the options-dialog. +</p><p> + Note that when you write to a completely new directory then you usually also want to copy the identical files. + In that case enable the "Show Identical Files"-option. If your destination-directory is one of the inputs, + then this isn't necessary because the file is already there. +</p><p> + If you are satisfied so far, the rest is easy. +</p><p> + To merge all items: Select "Start/Continue directory merge" in the "Directory"-menu + or press F7 (which is the default shortcut). + To merge only the current item: Select "Run Operation For Current Item" + or press F6. +</p><p> + 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. +</p><p> + If you merge all items a dialog will appear giving you the options "Do it", "Simulate + it" and "Cancel". +</p><div class="itemizedlist"><ul type="disc"><li><p>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.</p></li><li><p>Otherwise select "Do it" to really start merging.</p></li></ul></div><p> + Then <span class="application">KDiff3</span> will run the specified operation for all items. If manual + interaction is required (single file merge), then a merge window will open + (<a href="screenshots.html#dirmergebigscreenshot">see the big screenshot</a>). +</p><p> + When you have finished with manually merging a file, again select "Start/Continue directory + merge" or the key F7. If you haven't saved it yet, a dialog will ask you to + do so. Then <span class="application">KDiff3</span> will continue with the next item. +</p><p> + When <span class="application">KDiff3</span> 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 (F7 key) <span class="application">KDiff3</span> 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. +</p><p> + When the merge is complete, then <span class="application">KDiff3</span> will inform you via a message + box. +</p><p> + If some items were merged individually before running the directorymerge then + <span class="application">KDiff3</span> remembers this (while this + merge-session goes on), and doesn't merge them again when later the merge for + all items is run. Even when the merge was skipped or nothing was saved these + items count as completed. Only when you change the merge operation the + "Done"-status of the item will be removed and it can be merged again. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="dirmergevisible.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dirmergeoptions.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Directory Merge Visible Information </div><div class="navRight"> Options for Comparing and Merging Directories</div><div class="navCenter"><a accesskey="u" href="dirmerge.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/faq.html b/doc/en/faq.html new file mode 100644 index 0000000..530e30e --- /dev/null +++ b/doc/en/faq.html @@ -0,0 +1,132 @@ +<html><head><title>Chapter 5. Questions and Answers</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="index.html" title="The KDiff3 Handbook"><link rel="prev" href="kpart.html" title="Using KDiff3 as a KPart"><link rel="next" href="credits.html" title="Chapter 6. Credits and License"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Questions and Answers</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="kpart.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="credits.html">Next</a></div><div class="navCenter"> </div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="faq"></a>Chapter 5. Questions and Answers</h2></div></div></div><p>This document may have been updated since your installation. +You can find the latest version at <a href="http://docs.kde.org/development/en/extragear-utils/" target="_top">http://docs.kde.org/development/en/extragear-utils/</a>.</p><div class="qandaset"><dl><dt>5.1. <a href="faq.html#id2570336"> + Why is it called "KDiff3"? +</a></dt><dt>5.2. <a href="faq.html#id2569721"> + Why did I release it under GPL? +</a></dt><dt>5.3. <a href="faq.html#id2569735"> + Some buttons and functions are missing. What's wrong? +</a></dt><dt>5.4. <a href="faq.html#id2569763"> + Often lines that are similar but not identical appear next to each other + but sometimes not. Why? +</a></dt><dt>5.5. <a href="faq.html#id2569787"> + Why must all conflicts be solved before the merge result can be saved? +</a></dt><dt>5.6. <a href="faq.html#id2569806"> + How can I synchronise the diff and merge views, so that all views show the same text position? +</a></dt><dt>5.7. <a href="faq.html#id2569826"> + Why does the editor in the merge result window not have an "undo"-function? +</a></dt><dt>5.8. <a href="faq.html#id2569841"> + When I removed some text, then suddenly "<No src line>" appeared + and cannot be deleted. What does that mean and how can one remove this? +</a></dt><dt>5.9. <a href="faq.html#id2569879"> + Why doesn't KDiff3 support syntax-highlighting? +</a></dt><dt>5.10. <a href="faq.html#id2569900"> + Can I use KDiff3 to compare OpenOffice.Org, Word, Excel, PDF-, etc. files? +</a></dt><dt>5.11. <a href="faq.html#id2569967"> + Where has the the directory option "List only deltas" gone? +</a></dt><dt>5.12. <a href="faq.html#id2569988"> + How can I make a big selection in the diff input window + because scrolling takes so long? +</a></dt><dt>5.13. <a href="faq.html#id2570009"> + There is so much information here, but your question is still not answered? +</a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%"><tbody><tr class="question"><td align="left" valign="top"><a name="id2570336"></a><a name="id2570338"></a><b>5.1.</b></td><td align="left" valign="top"><p> + Why is it called "<span class="application">KDiff3</span>"? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + 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. +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569721"></a><a name="id2569723"></a><b>5.2.</b></td><td align="left" valign="top"><p> + Why did I release it under GPL? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + 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. +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569735"></a><a name="id2569748"></a><b>5.3.</b></td><td align="left" valign="top"><p> + Some buttons and functions are missing. What's wrong? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + 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. +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569763"></a><a name="id2569764"></a><b>5.4.</b></td><td align="left" valign="top"><p> + Often lines that are similar but not identical appear next to each other + but sometimes not. Why? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + 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. + See also <a href="interpretinginformation.html#manualdiffhelp" title="Manually Aligning Lines">Manual Diff Help</a>. +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569787"></a><a name="id2569789"></a><b>5.5.</b></td><td align="left" valign="top"><p> + Why must all conflicts be solved before the merge result can be saved? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + 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. +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569806"></a><a name="id2569807"></a><b>5.6.</b></td><td align="left" valign="top"><p> + How can I synchronise the diff and merge views, so that all views show the same text position? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + Click into the summary column left of the text. (<a href="merging.html#synchronise_views" title="Setting The Current Group And Synchronising Merge And Diff View Position">See also here.</a>) +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569826"></a><a name="id2569827"></a><b>5.7.</b></td><td align="left" valign="top"><p> + Why does the editor in the merge result window not have an "undo"-function? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + 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. +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569841"></a><a name="id2569843"></a><b>5.8.</b></td><td align="left" valign="top"><p> + When I removed some text, then suddenly "<No src line>" appeared + and cannot be deleted. What does that mean and how can one remove this? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + 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). +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569879"></a><a name="id2569881"></a><b>5.9.</b></td><td align="left" valign="top"><p> + Why doesn't <span class="application">KDiff3</span> support syntax-highlighting? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + <span class="application">KDiff3</span> already uses many colors for difference highlighting. More + highlighting would be confusing. Use another editor for this. +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569900"></a><a name="id2569901"></a><b>5.10.</b></td><td align="left" valign="top"><p> + Can I use <span class="application">KDiff3</span> to compare OpenOffice.Org, Word, Excel, PDF-, <span class="abbrev">etc.</span> files? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + Although <span class="application">KDiff3</span> will analyse any kind of file the result will probably + not be very satisfactory for you. +</p><p> + <span class="application">KDiff3</span> was made to compare pure text files. OpenOffice, Word, Excel etc. + store much more information in the files (about fonts, pictures, pages, + colors etc.) which <span class="application">KDiff3</span> doesn't know about. So <span class="application">KDiff3</span> will + show you the contents of the file interpreted as pure text, but + this might be unreadable or at least it will look very odd. +</p><p> + Since most programs nowadays store their contents in XML-format, you might + be able to read it as pure text. So if the change was only small, + <span class="application">KDiff3</span> still might help you. +</p><p> + The best solution if you only want to compare the text (without embedded + objects like pictures) is to use "Select All" and "Copy" in your program + to copy the interesting text to the clipoard and then in <span class="application">KDiff3</span> paste the + text into either diff input window. + (See also <a href="selections.html" title="Select, Copy And Paste">Select, Copy And Paste</a>.) +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569967"></a><a name="id2569969"></a><b>5.11.</b></td><td align="left" valign="top"><p> + Where has the the directory option "List only deltas" gone? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + There are now several <a href="dirmergevisible.html#selectingvisiblefiles" title="Selecting Listed Files">"Show"-options</a> in the directory menu. + Disabling "Show identical files" will achieve what enabling "List only deltas" used to do. +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2569988"></a><a name="id2569989"></a><b>5.12.</b></td><td align="left" valign="top"><p> + How can I make a big selection in the diff input window + because scrolling takes so long? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + Start the selection as usual (click and hold the left mouse button). + Then use the navigation keys (e.g. page up, page down) while holding the left mouse button down. + (See also <a href="selections.html" title="Select, Copy And Paste">Select, Copy And Paste</a>.) +</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2570009"></a><a name="id2570011"></a><b>5.13.</b></td><td align="left" valign="top"><p> + There is so much information here, but your question is still not answered? +</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p> + Please send me your question. I appreciate every comment. +</p></td></tr></tbody></table></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="kpart.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="credits.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Using <span class="application">KDiff3</span> as a KPart </div><div class="navRight"> Credits and License</div><div class="navCenter"><a accesskey="u" href="index.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/features.html b/doc/en/features.html new file mode 100644 index 0000000..e5ac9ed --- /dev/null +++ b/doc/en/features.html @@ -0,0 +1,22 @@ +<html><head><title>More Features</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="introduction.html" title="Chapter 1. Introduction"><link rel="prev" href="screenshots.html" title="Screenshots and Features"><link rel="next" href="documentation.html" title="Chapter 2. File Comparison And Merge"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">More Features</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="screenshots.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="documentation.html">Next</a></div><div class="navCenter">Introduction</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="features"></a>More Features</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2490911"></a> Line-By-Line And Char-By-Char Diff-Viewer</h3></div></div></div><p>By using the possiblities of a graphical color display <span class="application">KDiff3</span> shows + exactly what the difference is. When you have to do many code-reviews, you will like this. +</p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="letter_by_letter.png"><hr></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2490942"></a> See White-Space Differences At One Glance</h3></div></div></div><p>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.) +</p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="white_space.png"><hr></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2490972"></a> Triple-Diff</h3></div></div></div><p> Analyze three files and see where they differ. +</p><p> + The left/middle/right windows are named A/B/C and have the blue/green/magenta + color respectively. +</p><p> + 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. +</p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="triple_diff.png"><hr></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2491007"></a> Comfortable Merge Of Two Or Three Input Files</h3></div></div></div><p> <span class="application">KDiff3</span> 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2491031"></a>And ...</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>Fast navigation via buttons.</p></li><li><p>A mouse-click into a summary column sync's all windows to show the same position.</p></li><li><p>Select and copy from any window and paste into the merge result window.</p></li><li><p>Overview column that shows where the changes and conflicts are.</p></li><li><p>The colors are adjustable to your specific preferences.</p></li><li><p>Adjustable Tab size.</p></li><li><p>Option to insert spaces instead of tabs.</p></li><li><p>Open files comfortably via dialog or specify files on the command line.</p></li><li><p>Search for strings in all text windows. Find (Ctrl-F) and Find Next (F3)</p></li><li><p>Show the line numbers for each line. </p></li><li><p>Paste clipboard or drag text into a diff input window.</p></li><li><p>Networktransparency via KIO.</p></li><li><p>Can be used as diff-viewer in KDevelop 3.</p></li><li><p>Word-wrap for long lines.</p></li><li><p>Support for Unicode, UTF-8 and other codecs.</p></li><li><p>Support for right to left languages.</p></li><li><p>...</p></li></ul></div></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="screenshots.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="documentation.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Screenshots and Features </div><div class="navRight"> File Comparison And Merge</div><div class="navCenter"><a accesskey="u" href="introduction.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/find.html b/doc/en/find.html new file mode 100644 index 0000000..ead358b --- /dev/null +++ b/doc/en/find.html @@ -0,0 +1,10 @@ +<html><head><title>Finding Strings</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="saving.html" title="Saving"><link rel="next" href="printing.html" title="Printing"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Finding Strings</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="saving.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="printing.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="find"></a>Finding Strings</h2></div></div></div><p> + You can search for a string in any text-window of <span class="application">KDiff3</span>. 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 occurrence. 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. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="saving.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="printing.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Saving </div><div class="navRight"> Printing</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/index.docbook b/doc/en/index.docbook new file mode 100644 index 0000000..50425ed --- /dev/null +++ b/doc/en/index.docbook @@ -0,0 +1,2135 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kdiff3 "<application>KDiff3</application>"> + <!ENTITY kappname "&kdiff3;"> + <!ENTITY package "extragear-utils"> + <!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 at gmx.de</email> +</address></affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2002-2007</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>2007-31-03</date> +<releaseinfo>0.9.92</releaseinfo> + + +<abstract> +<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>has options to highlight or hide changes in white-space or comments,</para></listitem> +<listitem><para>supports Unicode, UTF-8 and other file encodings,</para></listitem> +<listitem><para>prints differences,</para></listitem> +<listitem><para>supports version control keyword and history merging.</para></listitem> +</itemizedlist> +</para><para> + This document describes &kdiff3;-version 0.9.92. +</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> +<keyword>white space</keyword> +<keyword>comments</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>Can be used as diff-viewer in KDevelop 3.</para></listitem> + <listitem><para>Word-wrap for long lines.</para></listitem> + <listitem><para>Support for Unicode, UTF-8 and other codecs.</para></listitem> + <listitem><para>Support for right to left languages.</para></listitem> + <listitem><para>...</para></listitem> +</itemizedlist> +</sect2> +</sect1> +</chapter> + +<chapter id="documentation"><title>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>Other command line options</title> +<para>To see all available command line options type</para> +<screen> +<command>kdiff3</command> --help +</screen> +<para>Example output:</para> +<screen> +Options: + -m, --merge Merge the input. + -b, --base file Explicit base file. For compatibility with certain tools. + -o, --output file Output file. Implies -m. E.g.: -o newfile.txt + --out file Output file, again. (For compatibility with certain tools.) + --auto No GUI if all conflicts are auto-solvable. (Needs -o file) + --qall Don't solve conflicts automatically. (For compatibility...) + --L1 alias1 Visible name replacement for input file 1 (base). + --L2 alias2 Visible name replacement for input file 2. + --L3 alias3 Visible name replacement for input file 3. + -L, --fname alias Alternative visible name replacement. Supply this once for every input. + --cs string Override a config setting. Use once for every setting. E.g.: --cs "AutoAdvance=1" + --confighelp Show list of config settings and current values. + --config file Use a different config file. +</screen> +<para>The option <option>--cs</option> allows you to adjust a configuration value that is otherwise only adjustable via the configure dialogs. +But be aware that when &kdiff3; then terminates the changed value will be stored along with the other settings. +With <option>--confighelp</option> you can find out the names of the available items and current values.</para> +<para>Via <option>--config</option> you can specify a different config file. When you often use &kdiff3; +with completely different setups this allows you to easily switch between them.</para> +</sect2> +<sect2><title>Ignorable command line options</title> +<para>Many people want to use &kdiff3; with some version control system. +But when that version control system calls &kdiff3; using command line parameters that &kdiff3; doesn't recognise, then &kdiff3; terminates with an error. +The integration settings allow to specify command line parameters that should be ignored by &kdiff3;. +They will appear in the usage help like in this example:</para> +<screen> + --<replaceable>foo</replaceable> Ignored. (User defined.) +</screen> +<variablelist> + <varlistentry><term><emphasis>Command line options to ignore:</emphasis></term><listitem><para> + A list of options, separated via semicolon ';'. When one of these options appears on the commandline, + then &kdiff3; will ignore it and run without reporting an error. + (Default is "u;query;html;abort").</para></listitem></varlistentry> +</variablelist> +<para>When this isn't enough, then it is recommended to write a shell script that does the option translation.</para> +</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 cannot 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>Comparing Files And Interpreting The Information In The Input Windows</title> +<screenshot><mediaobject> +<imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +<sect2><title>Info Line</title><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 editable filename, + a button for browsing, 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. +</para><para> + When you selected another file via browsing or finished editing the filename here + by pressing enter, the new file will be loaded and + compared with the already loaded file(s). +</para></sect2><sect2><title>Coloring</title><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></sect2><sect2><title>Summary Column</title><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. When word-wrap is enabled then this vertical + line appears dotted for wrapped lines. +</para></sect2><sect2><title>Overview Column</title><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></sect2><sect2 id="manualdiffhelp"><title>Manually Aligning Lines</title><para> + Sometimes the algorithm places the wrong lines next to each other. Or you want to compare + one piece of text with text at a completely different position in the other file. + For these situations you can manually instruct &kdiff3; to align certain lines. + Mark the text for which you want to improve the alignment with the mouse as you would + for copy and paste in the first diff view and then choose "Add Manual Diff Alignment" + in the "Diffview"-menu (keyboard shortcut "Ctrl-Y") . An orange bar will appear in + the summary column next to the chosen text. Repeat this for the second and + (if available) third diff view. &kdiff3; will immediately recalculate the differences everytime you do this. + and will align the chosen lines. Of course some of the previously matching lines in between + might not match anymore. +</para><para> + Currently merging doesn't support the use of manual diff help. +</para></sect2><sect2 id="joinsplitsections"><title>Manually Joining and Splitting Diff Sections</title><para> + In some cases &kdiff3; will see too many or too few diff sections for merging. In such a + case you can join or split existing sections. +</para><para> + Add new sections by first selecting text in the lines that belong together in either input window (as for copying to the clipboard). + Then choose "Split Diff At Selection" in the "Merge" menu. + Splits will be added above the first line and below the last line of the selected text. + If you only want to add one section, then select text beginning at another section-split. +</para><para> + For joining sections in either input window select something in the lines from the sections to join. + (You can join several sections in one step too.) Then choose "Join selected Diffs" in the "Merge"-menu. +</para></sect2> +</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><sect2><title>The Summary Column</title><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></sect2><sect2 id="synchronise_views"><title>Setting The Current Group And Synchronising Merge And Diff View Position</title><para> + When clicking into the summary column with the left mouse button in either + window then the beginning of the group belonging to that line will shown in all windows. + 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></sect2><sect2><title>Choosing Inputs A, B or C For Current Conflict And Editing</title><para> + The button bar below the menubar contains three input selector buttons + containing the letters "A", "B" and "C". Click the input selector + button to insert (or remove if already inserted) the lines from the respective source. + To choose the lines from several inputs click the respective buttons in the + needed order. For example if you want that the lines from "B" appear before + the lines from "A" in the output, first click "B", then "A". +</para><para> + If you use the auto-advance option + (<link linkend="autoadvance">"Automatically go to next unsolved conflict after source selection"</link>), + you should disable this before choosing lines from several inputs or if you want to + edit the lines after your choice. Otherwise &kdiff3; will jump to the next + conflict after choosing the first input. +</para><para> + It is often helpful directly edit the merge output. + The summary column will show "m" for every line that was manually modified. + When for instance the differences are aligned in a way that simply choosing + the inputs won't be satisfactory, then you can mark the needed text and use + normal <link linkend="selections">copy and paste</link> to put it into the merge output. +</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></sect2><sect2><title>Choosing Input A, B, or C for All Conflicts</title><para> + The normal merge will start by solving simple conflicts automatically. + But the "Merge"-menu provides some actions for other common needs. + If you have to select the same source for most conflicts, then you can + choose "A", "B" or "C" everywhere, or only for the remaining unsolved + conflicts, or for unsolved white space conflicts. If you want to decide every + single delta yourself, you can "Set deltas to conflicts". Or if you want to + return to the automatic choices of &kdiff3; then select + "Automatically solve simple conflicts". &kdiff3; then restarts the merge. + For actions that change your previous modifications &kdiff3; will ask for your + confirmation before proceeding. +</para><para> + Note: When choosing either source for unsolved white space conflicts and + the options "Ignore Numbers" or "Ignore C/C++ Comments" are used then changes in + numbers or comments will be treated like white space too. + +</para></sect2><sect2 id="vcskeywordsmergesupport"><title>Automatic Merge of Version Control Keywords and History (Log)</title><para> +Many version control systems support special keywords in the file. (e.g. "$Date$", +"$Header$", "$Author$", "$Log$" etc.) During the +check-in the version control system (VCS) changes these lines. For instance +"$Date$" will turn into "$Date: 2005/03/22 18:45:01 $". Since this line will +be different in every version of the file, it would require manual interaction +during the merge. +</para><para> +&kdiff3; offers automatic merge for these items. For simple lines that match the +"Auto merge regular expression"-option in all input-files &kdiff3; will choose +the line from B or - if available - from C. (Additionally it is necessary that the lines +in question line up in the comparison and the previous line contains no conflict.) +This auto merge can either be run immediately after a merge starts (activate the option +"Run regular expression auto merge on merge start") or later via the merge +menu "Run Regular Expression Auto Merge". +</para><para> +Automatic merge for version control history (also called "log") is also supported. +The history automerge can either run immediately when the merge starts by activating the +option "Merge version control history on merge start" or later via the merge menu +"Automatically Solve History Conflicts". +</para><para> +Usually the version control history begins with a line containing the keyword "$Log$". +This must be matched by the "History start regular expression"-option. +&kdiff3; detects which subsequent lines are in the history by analysing the leading characters +that came before the "$Log$"-keyword. If the same "leading comment"-characters also appears in the following +lines, then they are also included in the history. +</para><para> +During each check-in the VCS writes a unique line specifying version-, date- and time-information +followed by lines with user comments. +These lines form one history-entry. This history section grows with every check-in and the +most recent entries appear at the top (after the history start line). +</para><para> +When for parallel development two or more developers check-in a branch of the file then +the merge history will contain several entries that appear as conflicts during the merge +of the branches. Since merging these can become very tedious, &kdiff3; offers support with two +possible strategies: Just insert the history information from both contributors at the top +or sort the history information by a user defined key. +</para><para> +The just-insert-all-entries-method is easier to configure. &kdiff3; just needs a method to +detect, which lines belong to one history entry. Most VCS insert an empty line after each +history entry. If there are no other empty lines, this is a sufficient criterion for &kdiff3;. +Just set an empty "History entry start regular expression". If the empty line criterion +isn't sufficient, you can specify a regular expression to detect the history entry start. +</para><para> +Note that &kdiff3; will remove duplicate history entrys. If a history entry appeared several times +in the history of a input file, only one entry will remain in the output. +</para><para> +If you want to sort the history, then you have to specify how the sort key should be built. +Use parentheses in the "History entry start regular expression" to group parts of the regular +expression that should later be used for the sort key. +Then specify the "History entry start sort key order" specifying a comma "," separated list of +numbers referring to the position of the group in the regular expression. +</para><para> +Because this is not so easy to get right immediately, you are able to test and improve +the regular expressions and key-generation in a dedicated dialog by pressing the +"Test your regular expressions"-button. +</para><para>Example: Assume a history that looks like this: +<screen> +/************************************************************************** +** HISTORY: $Log: \toms_merge_main_view\MyApplication\src\complexalgorithm.cpp $ +** +** \main\integration_branch_12 2 Apr 2001 10:45:41 tom +** Merged branch simon_branch_15. +** +** \main\henry_bugfix_branch_7\1 30 Mar 2001 19:22:05 henry +** Improved the speed for subroutine convertToMesh(). +** Fixed crash. +**************************************************************************/ +</screen> +The history start line matches the regular expression ".*\$Log.*\$.*". Then follow +the history entries. +</para><para> +The line with the "$Log$"-keyword begins with two "*" after which follows a space. +&kdiff3; uses the first non-white-space string as "leading comment" and assumes that +the history ends in the first line without this leading comment. In this example the +last line ends with a string that also starts with two "*", but instead of a space +character more "*" follow. Hence this line ends the history. +</para><para> +If history sorting isn't required then the history entry start line regular expression +could look like this. (This line is split in two because it wouldn't fit otherwise.) +<screen> +\s*\\main\\\S+\s+[0-9]+ (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) + [0-9][0-9][0-9][0-9] [0-9][0-9]:[0-9][0-9]:[0-9][0-9]\s+.* +</screen> +For details about regular expressions please see the +<ulink url="http://doc.trolltech.com/3.3/qregexp.html#details">regular expression documentation by Trolltech</ulink>. +Note that "\s" (with lowercase "s") matches any white space and "\S" (with uppercase "S") matches any non-white-space. +In our example the history entry start contains first the version info with reg. exp. "\\main\\\S+", the date consisting of day "[0-9]+", month "(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)" and year "[0-9][0-9][0-9][0-9]", the time "[0-9][0-9]:[0-9][0-9]:[0-9][0-9]" and finally the developers login name ".*". +</para><para> +Note that the "leading comment"-characters (in the example "**") will already be removed by &kdiff3; +before trying to match, hence the regular expression begins with a match for none or more white-space characters "\s*". +Because comment characters can differ in each file (e.g. C/C++ uses other comment characters than a Perl script) +&kdiff3; takes care of the leading comment characters and you should not specify them in the regular expression. +</para><para> +If you require a sorted history. Then the sortkey must be calculated. For this the +relevant parts in the regular expression must be grouped by parentheses. +(The extra parentheses can also stay in if history sorting is disabled.) +<screen> +\s*\\main\\(\S+)\s+([0-9]+) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) + ([0-9][0-9][0-9][0-9]) ([0-9][0-9]:[0-9][0-9]:[0-9][0-9])\s+(.*) +</screen> +The parentheses now contain 1. version info, 2. day, 3. month, 4. year, 5. time, 6. name. +But if we want to sort by date and time, we need to construct a key with the elements in a different order of appearance: +First the year, followed by month, day, time, version info and name. Hence the sortkey order to specify is "4,3,2,5,1,6". +</para><para> +Because month names aren't good for sorting ("Apr" would be first) &kdiff3; detects in which order +the month names were given and uses that number instead ("Apr"->"04"). +And if a pure number is found it will be transformed to a 4-digit value with leading zeros for sorting. +Finally the resulting sort key for the first history entry start line will be: +<screen> +2001 04 0002 10:45:41 integration_branch_12 tom +</screen> +</para><para> +For more information also see <link linkend="mergeoptions">Merge Settings</link>. +</para> +</sect2> +</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="synchronise_views">"Setting The Current Group And Synchronising Merge And Diff View Position"</link>). +</para><para> + The button bar also contains nine 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> +<sect2 id="autoadvance"><title>Auto-Advance</title> +<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, &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> +</sect2> +</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> + If the selection exceeds the visible range you can move the mouse over the + window borders which causes &kdiff3; to scroll in that direction. +</para><para> + For very large selections you can also use the navigation keys while holding down + the mouse. E.g. use page up and page down to quickly go to a certain position. At the + end position release the mouse button. +</para><para> + In order to select everything in the current window use menu "Edit"->"Select All" (Ctrl-A). +</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. +</para><para> + "Paste" (Ctrl-V or Shift-Insert) inserts the text in the clipboard at the + cursorposition or over the current selection. + If you paste to either diff input window the contents of the clipboard will + be shown in that window and the comparison will restart immediately. This is + useful if you want to quickly grab a piece of text from somewhere and + compare it with something else without first creating files. +</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 occurrence. 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="printing"><title>Printing</title> +<para> + &kdiff3; supports printing for textfile differences. The "Print..."-command (Ctrl-P) + in the File-menu opens a dialog that allows you to select the printer and to adjust + other options. +</para><para> + There are several possibilities to adjust the range. Due to different printing + dialogs on different operating systems, the method to achieve certain range selections varies. +</para> +<variablelist> + <varlistentry><term>All:</term><listitem><para>Print everything.</para></listitem></varlistentry> + <varlistentry><term>Current:</term><listitem><para>Print a page starting at the first visible line in the window. + (On systems without this option this can be achived by specifying page number 10000 for printing.)</para></listitem></varlistentry> + <varlistentry><term>Selection:</term><listitem><para> + Before choosing to print select text with the mouse (like for copy and paste) + in one of the diff input windows to define the start and end line. If no text + in one of the diff input windows was selected, then this won't be an available + choice. (On systems without this option this can be achived by specifying page + number 9999 for printing.)</para></listitem></varlistentry> + <varlistentry><term>Range:</term><listitem><para>Specify the first and last page. + </para></listitem></varlistentry> +</variablelist> +<para> + Other important options for printing will be taken from the normal options: +</para><itemizedlist> + <listitem><para>Font, font size</para></listitem> + <listitem><para>Show line numbers</para></listitem> + <listitem><para>Word wrap</para></listitem> + <listitem><para>Colors</para></listitem> + <listitem><para>etc.</para></listitem> +</itemizedlist> +<para> + Landscape formatting is also recommended for printing. +</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> + <varlistentry><term><emphasis>Color for manually selected diff ranges:</emphasis></term><listitem><para> Usually orange.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Newest file color in directory comparison:</emphasis></term><listitem><para> Usually green.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Oldest file color in directory comparison:</emphasis></term><listitem><para> Usually red.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Middle age file color in directory comparison:</emphasis></term><listitem><para> Usually dark yellow.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Color for missing files in directory comparison:</emphasis></term><listitem><para> Usually black.</para></listitem></varlistentry> +</variablelist> +<para> + Changing the colors for directory comparison will be effective only when starting the next directory comparison. +</para> +<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> + <varlistentry><term><emphasis> Line end style:</emphasis></term><listitem><para> When saving you can select what line + end style you prefer. The default setting is the common choice for the used operating system. </para></listitem></varlistentry> +</variablelist> +</sect2> + +<sect2 id="diffoptions"><title>Diff 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>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>Ignore C/C++ comments:</emphasis></term><listitem><para> Default is off. + Changes in comments will be treated like changes in white space. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Ignore case:</emphasis></term><listitem><para> Default is off. + Case-differences of characters (like 'A' vs. 'a') will be treated like changes in white space. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Preprocessor-Command:</emphasis></term><listitem><para> + See <link linkend="preprocessors">next section</link>. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Line-Matching Preprocessor-Command:</emphasis></term><listitem><para> + See <link linkend="preprocessors">next section</link>. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Try Hard:</emphasis></term><listitem><para> + Try hard to find an even smaller delta. (Default is on.) This will probably + be effective for complicated and big files. And slow for very big files. + </para></listitem></varlistentry> +</variablelist> +</sect2> + +<sect2 id="mergeoptions"><title>Merge Settings</title> +<variablelist> + <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> + <varlistentry><term><emphasis>White space 2/3-file merge default:</emphasis></term><listitem><para> + Automatically solve all white-space conflict by choosing the specified file. + (Default is manual choice.) Useful if white space really isn't important in many files. + If you need this only occasionally better use "Choose A/B/C For All Unsolved Whitespace Conflicts" + in the merge menu. Note that if you enable either "Ignore numbers" or "Ignore C/C++ comments" + then this auto-choice also applies for conflicts in numbers or comments. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Auto merge regular expression:</emphasis></term><listitem><para> + Regular expression for lines where &kdiff3; should automatically choose one source. See also <link linkend="vcskeywordsmergesupport">Automatic Merge ...</link> + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Run regular expression auto merge on merge start:</emphasis></term><listitem><para> + If activated &kdiff3; runs the automatic merge using the "Auto merge regular expression" when a merge is started. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>History start regular expression:</emphasis></term><listitem><para> + Regular expression for the start of the merge history entry. + Usually this line contains the "$Log$"-keyword. + Default value: ".*\$Log.*\$.*" + </para></listitem></varlistentry> + <varlistentry><term><emphasis>History entry start regular expression:</emphasis></term><listitem><para> + A merge history entry consists of several lines. + Specify the regular expression to detect the first line (without the leading comment). + Use parentheses to group the keys you want to use for sorting. + If left empty, then &kdiff3; assumes that empty lines separate history entries. + See also <link linkend="vcskeywordsmergesupport">Automatic Merge ...</link> + </para></listitem></varlistentry> + <varlistentry><term><emphasis>History merge sorting:</emphasis></term><listitem><para> + Enable version control history sorting. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>History entry start sort key order:</emphasis></term><listitem><para> + Each parentheses used in the regular expression for the history start entry + groups a key that can be used for sorting. + Specify the list of keys (that are numbered in order of occurrence + starting with 1) using ',' as separator (e.g. "4,5,6,1,2,3,7"). + If left empty, then no sorting will be done. + See also <link linkend="vcskeywordsmergesupport">Automatic Merge ...</link> + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Merge version control history on merge start:</emphasis></term><listitem><para> + If activated &kdiff3; runs the automatic history merging using aforementioned options when a merge is started. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Max number of history entries:</emphasis></term><listitem><para> + &kdiff3; truncates the history list after the specified number of entries. Use -1 to avoid truncation. (Default is -1). + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Test your regular expressions</emphasis></term><listitem><para> + This button shows a dialog that allows you to improve and test the regular expressions above. + Just copy the respective data from your files into the example lines. The "Match results" + will immediately show whether the match succeeds or not. + The "Sort key result" will display the key used for history merge sorting. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Irrelevant merge command:</emphasis></term><listitem><para> + Specify a command of your own that should be called when &kdiff3; detects + that for a three file merge the file from B doesn't contribute any + relevant data that isn't already contained in the file from C. + The command is called with the three filenames as parameters. + Data matched by the "Auto merge regular expression" or in the + history isn't considered relevant. + </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>Regional and Language Options</title> + <variablelist> + <varlistentry><term><emphasis>Language:</emphasis></term><listitem><para>Adjust the language of the user interface. Changing this option doesn't affect the running program. You have to exit and restart &kdiff3; so that the language is changed. (This option is not available in the KDE version of &kdiff3; because the language is adjustable in the global KDE settings.) + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Use the same encoding for everything:</emphasis></term><listitem><para> The following encoding options can be adjusted separately for each item or if this option is true, all values will take the first value. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Local Encoding:</emphasis></term><listitem><para>Above the codec-selectors appears a note that tells you what the local encoding is. (This is not adjustable but for your information just in case you don't know your local encoding, but need to select it.) + </para></listitem></varlistentry> + <varlistentry><term><emphasis>File Encoding for A/B/C:</emphasis></term><listitem><para> Adjust the file encoding for input files. This has an effect on how the special characters are interpreted. Since you can adjust each codec separately you can even compare and merge files that were saved using different codecs. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>File Encoding for Merge Output and Saving:</emphasis></term><listitem><para> When you have edited a file, then you can adjust which encoding will be used when saving to disk. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>File Encoding for Preprocessor Files:</emphasis></term><listitem><para>When you define preprocessors then they might not be able to operate on your codec. (e.g.: Your files are 16-bit-unicode and your preprocessor can only take 8-bit-ascii.) With this option you can define the encoding of preprocessor output. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Right To Left Language:</emphasis></term><listitem><para>Some languages are written right to left. When this option is enabled, &kdiff3; draws the text from right to left in the diff input windows and in the merge output window. Note that if you start &kdiff3; with the command line option "--reverse" then all layouting will be done right to left too. (This is a feature provided by Qt.) This documentation was written assuming that "Right To Left Language" or reverse layout are disabled. So some references to "left" or "right" must be replaced by their respective counterpart if you use these options. + </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 white space:</emphasis></term><listitem><para> Turn this off to suppress + any highlighting of white-space-only changes in the text or overview-columns. + (Note that this also applies to changes in numbers or comments if the options "Ignore numbers" + or "Ignore C/C++ comments" are active.)</para></listitem></varlistentry> + <varlistentry><term><emphasis>Overview options:</emphasis></term><listitem><para> + These choices are only available when you compare three files. In normal mode all + differences are shown in one color-coded overview-column. But sometimes you are + especially interested in the differences between only two of these three files. + Selecting "A vs. B", "A vs. C" or "B vs. C"-overview will show a second overview + column with the required information next to the normal overview. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Word wrap diff windows:</emphasis></term><listitem><para> + Wrap lines when their length would exceed the width of a window. + </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> + +<sect1 id="preprocessors"><title>Preprocessor Commands</title> +<para> +&kdiff3; supports two preprocessor options. +</para><para> +<variablelist> + <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> +</variablelist> +</para> +<para> +The idea is to allow the user greater flexibility while configuring the diff-result. +But this requires an external program, and many users don't want to write one themselves. +The good news is that very often <command>sed</command> or <command>perl</command> +will do the job. +</para> +<para>Example: Simple testcase: Consider file a.txt (6 lines): +<screen> + aa + ba + ca + da + ea + fa +</screen> +And file b.txt (3 lines): +<screen> + cg + dg + eg +</screen> +Without a preprocessor the following lines would be placed next to each other: +<screen> + aa - cg + ba - dg + ca - eg + da + ea + fa +</screen> +This is probably not wanted since the first letter contains the actually interesting information. +To help the matching algorithm to ignore the second letter we can use a line matching preprocessor +command, that replaces 'g' with 'a': +<screen> + <command>sed</command> 's/g/a/' +</screen> +With this command the result of the comparison would be: +<screen> + aa + ba + ca - cg + da - dg + ea - eg + fa +</screen> +Internally the matching algorithm sees the files after running the line matching preprocessor, +but on the screen the file is unchanged. (The normal preprocessor would change the data also on +the screen.) +</para> + +<sect2 id="sedbasics"><title><command>sed</command> Basics</title> +<para> +This section only introduces some very basic features of <command>sed</command>. For more +information see <ulink url="info:/sed">info:/sed</ulink> or +<ulink url="http://www.gnu.org/software/sed/manual/html_mono/sed.html"> +http://www.gnu.org/software/sed/manual/html_mono/sed.html</ulink>. +A precompiled version for Windows can be found at <ulink url="http://unxutils.sourceforge.net"> +http://unxutils.sourceforge.net</ulink>. +Note that the following examples assume that the <command>sed</command>-command is in some +directory in the PATH-environment variable. If this is not the case, you have to specify the full absolute +path for the command. +</para> +<note><para>Also note that the following examples use the single quotation mark (') which won't work for Windows. +On Windows you should use the double quotation marks (") instead.</para></note> +<para> +In this context only the <command>sed</command>-substitute-command is used: +<screen> + <command>sed</command> 's/<replaceable>REGEXP</replaceable>/<replaceable>REPLACEMENT</replaceable>/<replaceable>FLAGS</replaceable>' +</screen> +Before you use a new command within &kdiff3;, you should first test it in a console. +Here the <command>echo</command>-command is useful. Example: +<screen> + <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/' + -> obrakadabra +</screen> +This example shows a very simple sed-command that replaces the first occurance +of "a" with "o". If you want to replace all occurances then you need the "g"-flag: +<screen> + <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/g' + -> obrokodobro +</screen> +The "|"-symbol is the pipe-command that transfers the output of the previous +command to the input of the following command. If you want to test with a longer file +then you can use <command>cat</command> on Unix-like systems or <command>type</command> +on Windows-like systems. <command>sed</command> will do the substitution for each line. +<screen> + <command>cat</command> <replaceable>filename</replaceable> | <command>sed</command> <replaceable>options</replaceable> +</screen> +</para> +</sect2> +<sect2 id="sedforkdiff3"><title>Examples For <command>sed</command>-Use In &kdiff3;</title> +<sect3><title>Ignoring Other Types Of Comments</title> +<para> +Currently &kdiff3; understands only C/C++ comments. Using the +Line-Matching-Preprocessor-Command you can also ignore +other types of comments, by converting them into C/C++-comments. + +Example: To ignore comments starting with "#", you would like to convert them +to "//". Note that you also must enable the "Ignore C/C++-Comments" option to get +an effect. An appropriate Line-Matching-Preprocessor-Command would be: + +<screen> + <command>sed</command> 's/#/\/\//' +</screen> +Since for <command>sed</command> the "/"-character has a special meaning, it is necessary to place the +"\"-character before each "/" in the replacement-string. Sometimes the "\" is required +to add or remove a special meaning of certain characters. The single quotation marks (') before +and after the substitution-command are important now, because otherwise the shell will +try to interpret some special characters like '#', '$' or '\' before passing them to +<command>sed</command>. <emphasis>Note that on Windows you will need the double quotation marks (") here. Windows +substitutes other characters like '%', so you might have to experiment a little bit.</emphasis> +</para> +</sect3> +<sect3><title>Caseinsensitive Diff</title> +<para> +Use the following Line-Matching-Preprocessor-Command to convert all input to uppercase: +<screen> + <command>sed</command> 's/\(.*\)/\U\1/' +</screen> +Here the ".*" is a regular expression that matches any string and in this context matches +all characters in the line. +The "\1" in the replacement string refers to the matched text within the first pair of "\(" and "\)". +The "\U" converts the inserted text to uppercase. +</para> +</sect3> + +<sect3><title>Ignoring Version Control Keywords</title> +<para> +CVS and other version control systems use several keywords to insert automatically +generated strings (<ulink url="info:/cvs/Keyword substitution">info:/cvs/Keyword substitution</ulink>). +All of them follow the pattern "$KEYWORD generated text$". We now need a +Line-Matching-Preprocessor-Command that removes only the generated text: +<screen> + <command>sed</command> 's/\$\(Revision\|Author\|Log\|Header\|Date\).*\$/\$\1\$/' +</screen> +The "\|" separates the possible keywords. You might want to modify this list +according to your needs. +The "\" before the "$" is necessary because otherwise the "$" matches the end of the line. +</para> +<para> +While experimenting with <command>sed</command> you might come to understand and even like +these regular expressions. They are useful because there are many other programs that also +support similar things. +</para> +</sect3> + +<sect3><title>Ignoring Numbers</title> +<para> +Ignoring numbers actually is a built-in option. But as another example, this is how +it would look as a Line-Matching-Preprocessor-command. +<screen> + <command>sed</command> 's/[0123456789.-]//g' +</screen> +Any character within '[' and ']' is a match and will be replaced with nothing. +</para> +</sect3> + +<sect3><title>Ignoring Certain Columns</title> +<para> +Sometimes a text is very strictly formatted, and contains columns that you always want to ignore, while there are +other columns you want to preserve for analysis. In the following example the first five columns (characters) are +ignored, the next ten columns are preserved, then again five columns are ignored and the rest of the line is preserved. +<screen> + <command>sed</command> 's/.....\(..........\).....\(.*\)/\1\2/' +</screen> +Each dot '.' matches any single character. The "\1" and "\2" in the replacement string refer to the matched text within the first +and second pair of "\(" and "\)" denoting the text to be preserved. +</para> +</sect3> + +<sect3><title>Combining Several Substitutions</title> +<para> +Sometimes you want to apply several substitutions at once. You can then use the +semicolon ';' to separate these from each other. Example: +<screen> + <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/g;s/\(.*\)/\U\1/' + -> OBROKODOBRO +</screen> +</para> +</sect3> + +<sect3><title>Using <command>perl</command> instead of <command>sed</command></title> +<para> +Instead of <command>sed</command> you might want to use something else like +<command>perl</command>. +<screen> + <command>perl</command> -p -e 's/<replaceable>REGEXP</replaceable>/<replaceable>REPLACEMENT</replaceable>/<replaceable>FLAGS</replaceable>' +</screen> +But some details are different in <command>perl</command>. Note that where +<command>sed</command> needed "\(" and "\)" <command>perl</command> +requires the simpler "(" and ")" without preceding '\'. Example: +<screen> + <command>sed</command> 's/\(.*\)/\U\1/' + <command>perl</command> -p -e 's/(.*)/\U\1/' +</screen> +</para> +</sect3> +</sect2> + +<sect2><title>Order Of Preprocessor Execution</title> +<para> +The data is piped through all internal and external preprocessors in the +following order: +</para> +<itemizedlist> +<listitem><para>Normal preprocessor,</para></listitem> +<listitem><para>Line-Matching-Preprocessor,</para></listitem> +<listitem><para>Ignore case (conversion to uppercase),</para></listitem> +<listitem><para>Detection of C/C++ comments,</para></listitem> +<listitem><para>Ignore numbers,</para></listitem> +<listitem><para>Ignore white space</para></listitem> +</itemizedlist> +<para> +The data after the normal preprocessor will be preserved for display and merging. The +other operations only modify the data that the line-matching-diff-algorithm sees. +</para><para> +In the rare cases where you use a normal preprocessor note that +the line-matching-preprocessor sees the output of the normal preprocessor as input. +</para> +</sect2> + +<sect2><title>Warning</title> +<para> +The preprocessor-commands are often very useful, but as with any option that modifies +your texts or hides away certain differences automatically, you might accidentally overlook +certain differences and in the worst case destroy important data. +</para><para> +For this reason during a merge if a normal preprocessor-command is being used &kdiff3; +will tell you so and ask you if it should be disabled or not. +But it won't warn you if a Line-Matching-Preprocessor-command is active. The merge will not complete until +all conflicts are solved. If you disabled "Show White Space" then the differences that +were removed with the Line-Matching-Preprocessor-command will also be invisible. If the +Save-button remains disabled during a merge (because of remaining conflicts), make sure to enable +"Show White Space". If you don't wan't to merge these less important differences manually +you can select "Choose [A|B|C] For All Unsolved White space Conflicts" in the Merge-menu. +</para> +</sect2> +</sect1> +</chapter> + + +<chapter id="dirmerge"><title>Directory Comparison and Merge with &kdiff3;</title> +<sect1 id="dirmergeintro"><title>Introduction into Directory Comparison and Merge</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 run the selected operation for all items (key F7) or the selected item (key F6),</para></listitem> + <listitem><para>... lets you continue the merge after manual interaction with key F7,</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 F7. (More details later.) +</para> +</sect2> +</sect1> + +<sect1 id="dirmergevisible"><title>Directory Merge 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. (You can also + select the most needed operations via keyboard. + Ctrl+1/2/3/4/Del will select A/B/C/Merge/Delete respectively if available.) + 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> + +<sect2 id="statisticscolulmns"><title>Statistics Columns</title> +<para> + When the file comparison mode "Full Analysis" is enabled in the options, then + &kdiff3; will show extra columns containing the numbers of unsolved, solved, nonwhite and whitespace + conflicts. (The solved-column will only show when comparing or merging three directories.) +</para> +</sect2> + +<sect2 id="selectingvisiblefiles"><title>Selecting Listed Files</title> +<para> + Several options influence which files are listed here. Some are accessible in the + <link linkend="dirmergeoptions">settings dialog</link>. The Directory-menu contains the entries: +</para><para><itemizedlist> + <listitem><para>"Show Identical Files": Files that have been detected equal in all input directories.</para></listitem> + <listitem><para>"Show Different Files": Files that exist in two or more directories but are not equal.</para></listitem> + <listitem><para>"Show Files only in A": Files that exist only in A, but not in B or C.</para></listitem> + <listitem><para>"Show Files only in B": Files that exist only in B, but not in A or B.</para></listitem> + <listitem><para>"Show Files only in C": Files that exist only in C, but not in A or B.</para></listitem> +</itemizedlist></para> +<para> + Activate only the "Show"-options for the items you want listed. If for example you only want to list all items that + exist either in A or in B but not in both, you'll have to activate "Show Files only in A" and "Show Files only in B" + and deactivate all others ("Show Identical Files", "Show Different Files", "Show Files only in C"). + The list will be updated immediately to reflect the change. +</para><para> + These options also apply for directories with one exception: Disabling "Show Different Files" will not hide + any complete directories. This will work only for files within. +</para><para> + Note that of these only the "Show Identical Files"-option is persistant. The others are enabled when starting &kdiff3;. +</para> +</sect2> + +</sect1> + + +<sect1 id="dothemerge"><title>Doing A Directory Merge</title> +<para> + You can either merge the currently selected item (file or directory), or all items. + 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><link linkend="selectingvisiblefiles">"Show"-options</link> (Show Identical/Different Files, Files only in A/B/C)</para></listitem> +</itemizedlist> +<para> + If you change the settings in order to list more files, you must do a rescan via menu "Directory"->"Rescan" yourself. + (The reason for this is that for faster comparison-speed &kdiff3; omits the comparison for files suppressed by these criteria.) + If you changed your file and dir patterns to exclude files, then the file-list will immediately be updated on closing + the options-dialog. +</para><para> + Note that when you write to a completely new directory then you usually also want to copy the identical files. + In that case enable the "Show Identical Files"-option. If your destination-directory is one of the inputs, + then this isn't necessary because the file is already there. +</para><para> + If you are satisfied so far, the rest is easy. +</para><para> + To merge all items: Select "Start/Continue directory merge" in the "Directory"-menu + or press F7 (which is the default shortcut). + To merge only the current item: Select "Run Operation For Current Item" + or press F6. +</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> + If you merge all items 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 manually merging a file, again select "Start/Continue directory + merge" or the key F7. If you haven't saved it 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 (F7 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><para> + If some items were merged individually before running the directorymerge then + &kdiff3; remembers this (while this + merge-session goes on), and doesn't merge them again when later the merge for + all items is run. Even when the merge was skipped or nothing was saved these + items count as completed. Only when you change the merge operation the + "Done"-status of the item will be removed and it can be merged again. +</para> +</sect1> + +<sect1 id="dirmergeoptions"><title>Options for Comparing and Merging Directories</title> +<para> + The &kdiff3;-preferences (menu "Settings"->"Configure &kdiff3;") 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 by using + the semicolon ";" as separator. Valid wildcards: '*' and '?'. (e.g. "*.cpp;*.h"). + Default is "*". This pattern is not used on directories.</para></listitem></varlistentry> + <varlistentry><term><emphasis>File Anti-Pattern(s):</emphasis></term><listitem><para> Files 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;*.obj".</para></listitem></varlistentry> + <varlistentry><term><emphasis>Directory Anti-Pattern(s):</emphasis></term><listitem><para> 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 "CVS;deps;.svn".</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 file systems 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>Case Sensitive Filename Comparison:</emphasis></term><listitem><para> + Default is false on Windows, true for other operating systems.</para></listitem></varlistentry> + <varlistentry><term><emphasis>File Comparison Mode:</emphasis></term><listitem><para> +<variablelist> + <varlistentry><term><emphasis>Binary Comparison:</emphasis></term><listitem><para> + This is the default file comparison mode. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Full Analysis:</emphasis></term><listitem><para> + Do a full analysis of each file and show the statistics information columns. + (Number of solved, unsolved, nonwhite and white conflicts.) + The full analysis is slower than a simple binary analysis, and much + slower when used on files that don't contain text. + (Specify the appropriate file-antipatterns.) + </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>Trust the size:</emphasis></term><listitem><para> + Similar to trusting the modification date. No real comparison happens. Two + files are considered equal if their file-sizes are equal. This is useful + when the file-copy operation didn't preserve the modification date. + Use this option with care. Default is off.</para></listitem></varlistentry> +</variablelist></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 you know, 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 in Directory Merge Window</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 by selecting it and + choosing "Merge current file" in the "Merge"-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> +<sect2><title>Comparing or Merging Files with Different Names</title> +<para> + Sometimes you need to compare or merge files with different names (e.g. the current + file and the backup in the same folder). +</para><para> + Select the exact file by clicking onto the icon in the column A, B or C. The first + file selected thus will be marked with an "A", the second and third with "B" and "C" + regardless on what column they are in. Only up to three files can be chosen like this. +</para><para> + Proceed by choosing "Compare Explicitely Selected Files" or "Merge Explicitely + Selected Files" from the "Directory"-menu. For your convenience these menu entries + also appear as context menu when you right-click the last selected file. +</para><para> + The comparison or merge of a file will happen in the same window. + If this method is used for directories a new window will be opened. +</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 resources 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 file system 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. (See the option "Trust the size".) + (To modify permissions or modification time is 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. + See also <link linkend="manualdiffhelp">Manual Diff Help</link>. +</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> + How can I synchronise the diff and merge views, so that all views show the same text position? +</para></question><answer><para> + Click into the summary column left of the text. (<link linkend="synchronise_views">See also here.</link>) +</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 cannot 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> + Can I use &kdiff3; to compare OpenOffice.Org, Word, Excel, PDF-, &etc; files? +</para></question><answer><para> + Although &kdiff3; will analyse any kind of file the result will probably + not be very satisfactory for you. +</para><para> + &kdiff3; was made to compare pure text files. OpenOffice, Word, Excel etc. + store much more information in the files (about fonts, pictures, pages, + colors etc.) which &kdiff3; doesn't know about. So &kdiff3; will + show you the contents of the file interpreted as pure text, but + this might be unreadable or at least it will look very odd. +</para><para> + Since most programs nowadays store their contents in XML-format, you might + be able to read it as pure text. So if the change was only small, + &kdiff3; still might help you. +</para><para> + The best solution if you only want to compare the text (without embedded + objects like pictures) is to use "Select All" and "Copy" in your program + to copy the interesting text to the clipoard and then in &kdiff3; paste the + text into either diff input window. + (See also <link linkend="selections">Select, Copy And Paste</link>.) +</para></answer></qandaentry> + +<qandaentry><question><para> + Where has the the directory option "List only deltas" gone? +</para></question><answer><para> + There are now several <link linkend="selectingvisiblefiles">"Show"-options</link> in the directory menu. + Disabling "Show identical files" will achieve what enabling "List only deltas" used to do. +</para></answer></qandaentry> + +<qandaentry><question><para> + How can I make a big selection in the diff input window + because scrolling takes so long? +</para></question><answer><para> + Start the selection as usual (click and hold the left mouse button). + Then use the navigation keys (e.g. page up, page down) while holding the left mouse button down. + (See also <link linkend="selections">Select, Copy And Paste</link>.) +</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-2007 Joachim Eibl <email>joachim.eibl at 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-2007 Joachim Eibl <email>joachim.eibl at 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. +</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>If you don't use KDE don't use <command>configure</command> but follow the instructions for Qt-only systems in the README file.</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 +--> diff --git a/doc/en/index.html b/doc/en/index.html new file mode 100644 index 0000000..6f9a4a8 --- /dev/null +++ b/doc/en/index.html @@ -0,0 +1,16 @@ +<html><head><title>The KDiff3 Handbook</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="description" content=" + KDiff3 is a file and directory diff and merge tool which +compares and merges two or three text input files or directories,shows the differences line by line and character by character(!),provides an automatic merge-facility,has an editor for comfortable solving of merge-conflicts,provides networktransparency via KIO,has options to highlight or hide changes in white-space or comments,supports Unicode, UTF-8 and other file encodings,prints differences,supports version control keyword and history merging. + + This document describes KDiff3-version 0.9.92. +"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="next" href="introduction.html" title="Chapter 1. Introduction"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">The <span class="application">KDiff3</span> Handbook</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="introduction.html">Next</a></div><div class="navCenter"> </div></div><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id2421696"></a>The <span class="application">KDiff3</span> Handbook</h1></div><div><div class="authorgroup"><p class="author"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="firstname">Joachim</span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="surname">Eibl</span> <code class="email"><joachim.eibl at gmx.de></code></p></div></div><div>Revision <span class="releaseinfo">0.9.92 (<span class="date">2007-31-03</span>)</span></div><div><p class="copyright">Copyright © 2002-2007 Joachim Eibl</p></div><div><div class="legalnotice"><a name="id2564266"></a><p>Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, +Version 1.1 or any later version published by the Free Software +Foundation; with no Invariant Sections, with no Front-Cover Texts, and +with no Back-Cover Texts. A copy of the license is included in <a href="credits.html#gnu-fdl">the section entitled "GNU Free Documentation License"</a>.</p></div></div><div><div><div class="abstract"><p> + <span class="application">KDiff3</span> is a file and directory diff and merge tool which +<div class="itemizedlist"><ul type="disc"><li><p>compares and merges two or three text input files or directories,</p></li><li><p>shows the differences line by line and character by character(!),</p></li><li><p>provides an automatic merge-facility,</p></li><li><p>has an editor for comfortable solving of merge-conflicts,</p></li><li><p>provides networktransparency via KIO,</p></li><li><p>has options to highlight or hide changes in white-space or comments,</p></li><li><p>supports Unicode, UTF-8 and other file encodings,</p></li><li><p>prints differences,</p></li><li><p>supports version control keyword and history merging.</p></li></ul></div> +</p><p> + This document describes <span class="application">KDiff3</span>-version 0.9.92. +</p></div></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="introduction.html">1. Introduction</a></span></dt><dd><dl><dt><span class="sect1"><a href="introduction.html#why">Yet Another Diff Frontend?</a></span></dt><dt><span class="sect1"><a href="screenshots.html">Screenshots and Features</a></span></dt><dt><span class="sect1"><a href="features.html">More Features</a></span></dt><dd><dl><dt><span class="sect2"><a href="features.html#id2490911"> Line-By-Line And Char-By-Char Diff-Viewer</a></span></dt><dt><span class="sect2"><a href="features.html#id2490942"> See White-Space Differences At One Glance</a></span></dt><dt><span class="sect2"><a href="features.html#id2490972"> Triple-Diff</a></span></dt><dt><span class="sect2"><a href="features.html#id2491007"> Comfortable Merge Of Two Or Three Input Files</a></span></dt><dt><span class="sect2"><a href="features.html#id2491031">And ...</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="documentation.html">2. File Comparison And Merge</a></span></dt><dd><dl><dt><span class="sect1"><a href="documentation.html#commandline">Command-Line Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="documentation.html#id2488302">Comparing 2 files: </a></span></dt><dt><span class="sect2"><a href="documentation.html#id2488321">Merging 2 files: </a></span></dt><dt><span class="sect2"><a href="documentation.html#id2488352">Comparing 3 files: </a></span></dt><dt><span class="sect2"><a href="documentation.html#id2488370">Merging 3 files: </a></span></dt><dt><span class="sect2"><a href="documentation.html#id2488418">Special case: Files with the same name </a></span></dt><dt><span class="sect2"><a href="documentation.html#id2488444">Commandline for starting a directory comparison or merge: </a></span></dt><dt><span class="sect2"><a href="documentation.html#id2488514">Other command line options</a></span></dt><dt><span class="sect2"><a href="documentation.html#id2488593">Ignorable command line options</a></span></dt></dl></dd><dt><span class="sect1"><a href="opendialog.html">Open-Dialog</a></span></dt><dt><span class="sect1"><a href="pasteinput.html">Paste and Drop Input</a></span></dt><dt><span class="sect1"><a href="interpretinginformation.html">Comparing Files And Interpreting The Information In The Input Windows</a></span></dt><dd><dl><dt><span class="sect2"><a href="interpretinginformation.html#id2564410">Info Line</a></span></dt><dt><span class="sect2"><a href="interpretinginformation.html#id2564428">Coloring</a></span></dt><dt><span class="sect2"><a href="interpretinginformation.html#id2564454">Summary Column</a></span></dt><dt><span class="sect2"><a href="interpretinginformation.html#id2564475">Overview Column</a></span></dt><dt><span class="sect2"><a href="interpretinginformation.html#manualdiffhelp">Manually Aligning Lines</a></span></dt><dt><span class="sect2"><a href="interpretinginformation.html#joinsplitsections">Manually Joining and Splitting Diff Sections</a></span></dt></dl></dd><dt><span class="sect1"><a href="merging.html">Merging And The Merge Output Editor Window</a></span></dt><dd><dl><dt><span class="sect2"><a href="merging.html#id2564630">The Summary Column</a></span></dt><dt><span class="sect2"><a href="merging.html#synchronise_views">Setting The Current Group And Synchronising Merge And Diff View Position</a></span></dt><dt><span class="sect2"><a href="merging.html#id2564684">Choosing Inputs A, B or C For Current Conflict And Editing</a></span></dt><dt><span class="sect2"><a href="merging.html#id2564761">Choosing Input A, B, or C for All Conflicts</a></span></dt><dt><span class="sect2"><a href="merging.html#vcskeywordsmergesupport">Automatic Merge of Version Control Keywords and History (Log)</a></span></dt></dl></dd><dt><span class="sect1"><a href="navigation.html">Navigation And Editing</a></span></dt><dd><dl><dt><span class="sect2"><a href="navigation.html#autoadvance">Auto-Advance</a></span></dt></dl></dd><dt><span class="sect1"><a href="selections.html">Select, Copy And Paste</a></span></dt><dt><span class="sect1"><a href="saving.html">Saving</a></span></dt><dt><span class="sect1"><a href="find.html">Finding Strings</a></span></dt><dt><span class="sect1"><a href="printing.html">Printing</a></span></dt><dt><span class="sect1"><a href="options.html">Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="options.html#id2566321">Font</a></span></dt><dt><span class="sect2"><a href="options.html#id2566353">Colors</a></span></dt><dt><span class="sect2"><a href="options.html#id2566534">Editor Settings</a></span></dt><dt><span class="sect2"><a href="options.html#diffoptions">Diff Settings</a></span></dt><dt><span class="sect2"><a href="options.html#mergeoptions">Merge Settings</a></span></dt><dt><span class="sect2"><a href="options.html#id2566994">Directory Merge</a></span></dt><dt><span class="sect2"><a href="options.html#id2567038">Regional and Language Options</a></span></dt><dt><span class="sect2"><a href="options.html#id2567171">Miscellaneous</a></span></dt><dt><span class="sect2"><a href="options.html#shortcuts">Configuring Keyboard-Shortcuts</a></span></dt></dl></dd><dt><span class="sect1"><a href="preprocessors.html">Preprocessor Commands</a></span></dt><dd><dl><dt><span class="sect2"><a href="preprocessors.html#sedbasics"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> Basics</a></span></dt><dt><span class="sect2"><a href="preprocessors.html#sedforkdiff3">Examples For <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>-Use In <span class="application">KDiff3</span></a></span></dt><dt><span class="sect2"><a href="preprocessors.html#id2567900">Order Of Preprocessor Execution</a></span></dt><dt><span class="sect2"><a href="preprocessors.html#id2567963">Warning</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="dirmerge.html">3. Directory Comparison and Merge with <span class="application">KDiff3</span></a></span></dt><dd><dl><dt><span class="sect1"><a href="dirmerge.html#dirmergeintro">Introduction into Directory Comparison and Merge</a></span></dt><dt><span class="sect1"><a href="startingdirmerge.html">Starting Directory Comparison Or Merge</a></span></dt><dd><dl><dt><span class="sect2"><a href="startingdirmerge.html#id2568158">Compare/Merge two directories: </a></span></dt><dt><span class="sect2"><a href="startingdirmerge.html#id2568202">Compare/Merge three directories: </a></span></dt></dl></dd><dt><span class="sect1"><a href="dirmergevisible.html">Directory Merge Visible Information</a></span></dt><dd><dl><dt><span class="sect2"><a href="dirmergevisible.html#name">The Name Column</a></span></dt><dt><span class="sect2"><a href="dirmergevisible.html#coloring">The Columns A/B/C and the Coloring Scheme</a></span></dt><dt><span class="sect2"><a href="dirmergevisible.html#operation">The Operation Column</a></span></dt><dt><span class="sect2"><a href="dirmergevisible.html#status">The Status Column</a></span></dt><dt><span class="sect2"><a href="dirmergevisible.html#statisticscolulmns">Statistics Columns</a></span></dt><dt><span class="sect2"><a href="dirmergevisible.html#selectingvisiblefiles">Selecting Listed Files</a></span></dt></dl></dd><dt><span class="sect1"><a href="dothemerge.html">Doing A Directory Merge</a></span></dt><dt><span class="sect1"><a href="dirmergeoptions.html">Options for Comparing and Merging Directories</a></span></dt><dt><span class="sect1"><a href="other.html">Other Functions in Directory Merge Window</a></span></dt><dd><dl><dt><span class="sect2"><a href="other.html#id2569323">Split/Full Screen Mode</a></span></dt><dt><span class="sect2"><a href="other.html#id2569341">Comparing or Merging a Single File</a></span></dt><dt><span class="sect2"><a href="other.html#id2569364">Comparing or Merging Files with Different Names</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="misc.html">4. Miscellaneous Topics</a></span></dt><dd><dl><dt><span class="sect1"><a href="misc.html#networktransparency">Networktransparency via KIO</a></span></dt><dd><dl><dt><span class="sect2"><a href="misc.html#id2569419">KIO-Slaves</a></span></dt><dt><span class="sect2"><a href="misc.html#id2569517">How To Write URLs</a></span></dt><dt><span class="sect2"><a href="misc.html#id2569553">Capabilities of KIO-Slaves</a></span></dt></dl></dd><dt><span class="sect1"><a href="kpart.html">Using <span class="application">KDiff3</span> as a KPart</a></span></dt></dl></dd><dt><span class="chapter"><a href="faq.html">5. Questions and Answers</a></span></dt><dt><span class="chapter"><a href="credits.html">6. Credits and License</a></span></dt><dt><span class="appendix"><a href="installation.html">A. Installation</a></span></dt><dd><dl><dt><span class="sect1"><a href="installation.html#getting-kdiff3">How to obtain <span class="application">KDiff3</span></a></span></dt><dt><span class="sect1"><a href="requirements.html">Requirements</a></span></dt><dt><span class="sect1"><a href="compilation.html">Compilation and Installation</a></span></dt></dl></dd></dl></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="introduction.html">Next</a></div><div align="center"> </div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft"> </div><div class="navRight"> Introduction</div><div class="navCenter"> </div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/installation.html b/doc/en/installation.html new file mode 100644 index 0000000..4ec8498 --- /dev/null +++ b/doc/en/installation.html @@ -0,0 +1,6 @@ +<html><head><title>Appendix A. Installation</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="index.html" title="The KDiff3 Handbook"><link rel="prev" href="credits.html" title="Chapter 6. Credits and License"><link rel="next" href="requirements.html" title="Requirements"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Installation</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="credits.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="requirements.html">Next</a></div><div class="navCenter"> </div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="installation"></a>Appendix A. Installation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="installation.html#getting-kdiff3">How to obtain <span class="application">KDiff3</span></a></span></dt><dt><span class="sect1"><a href="requirements.html">Requirements</a></span></dt><dt><span class="sect1"><a href="compilation.html">Compilation and Installation</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="getting-kdiff3"></a>How to obtain <span class="application">KDiff3</span></h2></div></div></div><p> +You can download the latest version of <span class="application">KDiff3</span> from its homepage <a href="http://kdiff3.sourceforge.net" target="_top">http://kdiff3.sourceforge.net</a>. +</p><p> +<span class="application">KDiff3</span> is also available for other platforms. See the homepage for details. +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="credits.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="requirements.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Credits and License </div><div class="navRight"> Requirements</div><div class="navCenter"><a accesskey="u" href="index.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/interpretinginformation.html b/doc/en/interpretinginformation.html new file mode 100644 index 0000000..90c15fd --- /dev/null +++ b/doc/en/interpretinginformation.html @@ -0,0 +1,68 @@ +<html><head><title>Comparing Files And Interpreting The Information In The Input Windows</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="pasteinput.html" title="Paste and Drop Input"><link rel="next" href="merging.html" title="Merging And The Merge Output Editor Window"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Comparing Files And Interpreting The Information In The Input Windows</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="pasteinput.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="merging.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interpretinginformation"></a>Comparing Files And Interpreting The Information In The Input Windows</h2></div></div></div><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="screenshot_diff.png"><hr></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564410"></a>Info Line</h3></div></div></div><p> + 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 editable filename, + a button for browsing, 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. +</p><p> + When you selected another file via browsing or finished editing the filename here + by pressing enter, the new file will be loaded and + compared with the already loaded file(s). +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564428"></a>Coloring</h3></div></div></div><p> + 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.) +</p><p> + 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 (<a href="merging.html" title="Merging And The Merge Output Editor Window">Merging</a>). +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564454"></a>Summary Column</h3></div></div></div><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.) +</p><p> + The vertical line separating the summary column and the text is interrupted + if the input file had no lines there. When word-wrap is enabled then this vertical + line appears dotted for wrapped lines. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564475"></a>Overview Column</h3></div></div></div><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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="manualdiffhelp"></a>Manually Aligning Lines</h3></div></div></div><p> + Sometimes the algorithm places the wrong lines next to each other. Or you want to compare + one piece of text with text at a completely different position in the other file. + For these situations you can manually instruct <span class="application">KDiff3</span> to align certain lines. + Mark the text for which you want to improve the alignment with the mouse as you would + for copy and paste in the first diff view and then choose "Add Manual Diff Alignment" + in the "Diffview"-menu (keyboard shortcut "Ctrl-Y") . An orange bar will appear in + the summary column next to the chosen text. Repeat this for the second and + (if available) third diff view. <span class="application">KDiff3</span> will immediately recalculate the differences everytime you do this. + and will align the chosen lines. Of course some of the previously matching lines in between + might not match anymore. +</p><p> + Currently merging doesn't support the use of manual diff help. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="joinsplitsections"></a>Manually Joining and Splitting Diff Sections</h3></div></div></div><p> + In some cases <span class="application">KDiff3</span> will see too many or too few diff sections for merging. In such a + case you can join or split existing sections. +</p><p> + Add new sections by first selecting text in the lines that belong together in either input window (as for copying to the clipboard). + Then choose "Split Diff At Selection" in the "Merge" menu. + Splits will be added above the first line and below the last line of the selected text. + If you only want to add one section, then select text beginning at another section-split. +</p><p> + For joining sections in either input window select something in the lines from the sections to join. + (You can join several sections in one step too.) Then choose "Join selected Diffs" in the "Merge"-menu. +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="pasteinput.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="merging.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Paste and Drop Input </div><div class="navRight"> Merging And The Merge Output Editor Window</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/introduction.html b/doc/en/introduction.html new file mode 100644 index 0000000..d7c2429 --- /dev/null +++ b/doc/en/introduction.html @@ -0,0 +1,32 @@ +<html><head><title>Chapter 1. Introduction</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="index.html" title="The KDiff3 Handbook"><link rel="prev" href="index.html" title="The KDiff3 Handbook"><link rel="next" href="screenshots.html" title="Screenshots and Features"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Introduction</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="index.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="screenshots.html">Next</a></div><div class="navCenter"> </div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="introduction"></a>Chapter 1. Introduction</h2></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="why"></a>Yet Another Diff Frontend?</h2></div></div></div><p> +Several graphical diff tools exist. Why choose <span class="application">KDiff3</span>? Let me say, why I wrote it. +</p><p> +<span class="application">KDiff3</span> 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. +</p><p> +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. +</p><p> +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. +</p><p> +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. +</p><p> +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. +</p><p> +A feature that required a big effort was the directory comparison and merge facility, which turned +the program almost into a full file browser. +</p><p> +I hope <span class="application">KDiff3</span> works for you too. Have fun! +</p><p> +Joachim Eibl (2003) +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="index.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="screenshots.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">The <span class="application">KDiff3</span> Handbook </div><div class="navRight"> Screenshots and Features</div><div class="navCenter"><a accesskey="u" href="index.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/iteminfo.png b/doc/en/iteminfo.png Binary files differnew file mode 100644 index 0000000..0b81443 --- /dev/null +++ b/doc/en/iteminfo.png diff --git a/doc/en/kdiff3.1 b/doc/en/kdiff3.1 new file mode 100644 index 0000000..3b9c492 --- /dev/null +++ b/doc/en/kdiff3.1 @@ -0,0 +1,89 @@ +.TH "KDIFF3" "1" +.SH "NAME" +KDiff3 \(em compares two or three input files or directories +.SH "SYNOPSIS" +.PP +\fBKDiff3\fR [\fBQT options\fP] [\fBKDE options\fP] [\fBKDiff3 options\fP] [\fB\fIFile1/base\fR\fP] [\fB\fIFile2\fR\fP] [\fB\fIFile3\fR\fP] +.SH "DESCRIPTION" +.PP +This manual page documents briefly the +\fBKDiff3\fR tool. +.PP +This manual page was written for the \fBDebian\fP distribution +because the original program does not have a manual page. +For comprehensive help, please see \fBkhelpcenter help:/kdiff3\fR. + +.PP +\fBKDiff3\fR is a program that + +.IP " \(bu" 6 +compares or merges two or three text input files or directories +.IP " \(bu" 6 +shows the differences line by line and character by character +.IP " \(bu" 6 +provides an automatic merge-facility and +.IP " \(bu" 6 +an integrated editor for comfortable solving of merge-conflicts +.IP " \(bu" 6 +supports Unicode, UTF-8 and other codecs +.IP " \(bu" 6 +supports KIO on KDE (allows accessing ftp, sftp, fish, smb etc.) +.IP " \(bu" 6 +Printing of differences +.IP " \(bu" 6 +Manual alignment of lines +.IP " \(bu" 6 +Automatic merging of version control history ($Log$) +.SH "OPTIONS" +.PP +This program follows the usual GNU command line syntax, +with long options starting with two dashes (`\-'). A summary of +options is included below. For a full summary of options, run +\fBKDiff3 \-\-help\fR. + +.IP "\fB-m, \-\-merge\fP " 10 +Merge the input. +.IP "\fB-b, \-\-base file\fP " 10 +Explicit base file. For compatibility with certain tools. +.IP "\fB-o, \-\-output file\fP " 10 +Output file. Implies \-m. E.g.: \-o newfile.txt +.IP "\fB\-\-out file\fP " 10 +Output file, again. (For compatibility with certain tools.) +.IP "\fB\-\-auto\fP " 10 +No GUI if all conflicts are auto-solvable. (Needs \-o file) +.IP "\fB\-\-qall\fP " 10 +Don't solve conflicts automatically. (For compatibility...) +.IP "\fB-L1 alias\fP " 10 +Visible name replacement for first file/base file. +.IP "\fB-L2 alias\fP " 10 +Visible name replacement for second file. +.IP "\fB-L3 alias\fP " 10 +Visible name replacement for third file. +.IP "\fB-L, \-\-fname alias\fP " 10 +Visible name replacement. May by supplied for each input. +.IP "\fB\-\-cs string\fP " 10 +Change a setting, e. g. \-\-cs "AutoAdvance=1". +.IP "\fB\-\-confighelp\fP " 10 +Show a list of all settings and their values. +.IP "\fB\-\-config file \fP " 10 +Use a different settings file. +.IP "\fB\-\-author\fP " 10 +Show author of program. +.IP "\fB-v, \-\-version\fP " 10 +Show version of program. +.IP "\fB\-\-license\fP " 10 +Show license of program. +.SH "AUTHOR" +.PP +This manual page was written by Eike Sauer <eikes@cs.tu-berlin.de> for +the \fBDebian\fP system (but may be used by others). Permission is +granted to copy, distribute and/or modify this document under +the terms of the GNU General Public License, Version 2 +(or, at your option, any later version published by the Free +Software Foundation). + +.PP +On Debian systems, the complete text of the GNU General Public +License can be found in /usr/share/common-licenses/GPL. + +.\" created by instant / docbook-to-man, Tue 13 Nov 2007, 15:25 diff --git a/doc/en/kpart.html b/doc/en/kpart.html new file mode 100644 index 0000000..63094d3 --- /dev/null +++ b/doc/en/kpart.html @@ -0,0 +1,22 @@ +<html><head><title>Using KDiff3 as a KPart</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="misc.html" title="Chapter 4. Miscellaneous Topics"><link rel="prev" href="misc.html" title="Chapter 4. Miscellaneous Topics"><link rel="next" href="faq.html" title="Chapter 5. Questions and Answers"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Using <span class="application">KDiff3</span> as a KPart</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="misc.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="faq.html">Next</a></div><div class="navCenter">Miscellaneous Topics</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kpart"></a>Using <span class="application">KDiff3</span> as a KPart</h2></div></div></div><p> +<span class="application">KDiff3</span> is a KPart. Currently it implements the KParts::ReadOnlyPart-interface. +</p><p> +It's main use is as difference-viewer in KDevelop. KDevelop always starts the +internal difference viewer first. To invoke <span class="application">KDiff3</span> press the right mouse button +on the difference viewer window and select "Show in KDiff3Part" from the contextmenu. +</p><p> +<span class="application">KDiff3</span> normally requires two complete files as input. When used as part <span class="application">KDiff3</span> +will assume that the inputfile is a patch-file in the unified format. <span class="application">KDiff3</span> +then retrieves the original filenames from the patch-file. At least one of +the two files must be available. <span class="application">KDiff3</span> will then invoke <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">patch</strong></span></span> to +recreate the second file. +</p><p> +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. +</p><p> +When run as a part <span class="application">KDiff3</span> only provides the a two-file-diff, a very small toolbar +and menu. Merging or directory-comparison are not supported then. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="misc.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="faq.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Miscellaneous Topics </div><div class="navRight"> Questions and Answers</div><div class="navCenter"><a accesskey="u" href="misc.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/letter_by_letter.png b/doc/en/letter_by_letter.png Binary files differnew file mode 100644 index 0000000..8ddd48a --- /dev/null +++ b/doc/en/letter_by_letter.png diff --git a/doc/en/merge_current.png b/doc/en/merge_current.png Binary files differnew file mode 100644 index 0000000..3f2e341 --- /dev/null +++ b/doc/en/merge_current.png diff --git a/doc/en/merging.html b/doc/en/merging.html new file mode 100644 index 0000000..7331292 --- /dev/null +++ b/doc/en/merging.html @@ -0,0 +1,195 @@ +<html><head><title>Merging And The Merge Output Editor Window</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="interpretinginformation.html" title="Comparing Files And Interpreting The Information In The Input Windows"><link rel="next" href="navigation.html" title="Navigation And Editing"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Merging And The Merge Output Editor Window</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="interpretinginformation.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="navigation.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="merging"></a>Merging And The Merge Output Editor Window</h2></div></div></div><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="screenshot_merge.png"><hr></div></div><p> + 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. +</p><p> + !!! Saving is disabled until all conflicts are resolved !!! (Use the "Go + to prev/next unsolved conflicts"-buttons to find the remaining conflicts.) +</p><p> + With only two input files every difference is also a conflict that must + be solved manually. +</p><p> + 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. +</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564630"></a>The Summary Column</h3></div></div></div><p> + 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="synchronise_views"></a>Setting The Current Group And Synchronising Merge And Diff View Position</h3></div></div></div><p> + When clicking into the summary column with the left mouse button in either + window then the beginning of the group belonging to that line will shown in all windows. + 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564684"></a>Choosing Inputs A, B or C For Current Conflict And Editing</h3></div></div></div><p> + The button bar below the menubar contains three input selector buttons + containing the letters "A", "B" and "C". Click the input selector + button to insert (or remove if already inserted) the lines from the respective source. + To choose the lines from several inputs click the respective buttons in the + needed order. For example if you want that the lines from "B" appear before + the lines from "A" in the output, first click "B", then "A". +</p><p> + If you use the auto-advance option + (<a href="navigation.html#autoadvance" title="Auto-Advance">"Automatically go to next unsolved conflict after source selection"</a>), + you should disable this before choosing lines from several inputs or if you want to + edit the lines after your choice. Otherwise <span class="application">KDiff3</span> will jump to the next + conflict after choosing the first input. +</p><p> + It is often helpful directly edit the merge output. + The summary column will show "m" for every line that was manually modified. + When for instance the differences are aligned in a way that simply choosing + the inputs won't be satisfactory, then you can mark the needed text and use + normal <a href="selections.html" title="Select, Copy And Paste">copy and paste</a> to put it into the merge output. +</p><p> + 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. +</p><p> + 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564761"></a>Choosing Input A, B, or C for All Conflicts</h3></div></div></div><p> + The normal merge will start by solving simple conflicts automatically. + But the "Merge"-menu provides some actions for other common needs. + If you have to select the same source for most conflicts, then you can + choose "A", "B" or "C" everywhere, or only for the remaining unsolved + conflicts, or for unsolved white space conflicts. If you want to decide every + single delta yourself, you can "Set deltas to conflicts". Or if you want to + return to the automatic choices of <span class="application">KDiff3</span> then select + "Automatically solve simple conflicts". <span class="application">KDiff3</span> then restarts the merge. + For actions that change your previous modifications <span class="application">KDiff3</span> will ask for your + confirmation before proceeding. +</p><p> + Note: When choosing either source for unsolved white space conflicts and + the options "Ignore Numbers" or "Ignore C/C++ Comments" are used then changes in + numbers or comments will be treated like white space too. + +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="vcskeywordsmergesupport"></a>Automatic Merge of Version Control Keywords and History (Log)</h3></div></div></div><p> +Many version control systems support special keywords in the file. (e.g. "$Date$", +"$Header$", "$Author$", "$Log$" etc.) During the +check-in the version control system (VCS) changes these lines. For instance +"$Date$" will turn into "$Date: 2005/03/22 18:45:01 $". Since this line will +be different in every version of the file, it would require manual interaction +during the merge. +</p><p> +<span class="application">KDiff3</span> offers automatic merge for these items. For simple lines that match the +"Auto merge regular expression"-option in all input-files <span class="application">KDiff3</span> will choose +the line from B or - if available - from C. (Additionally it is necessary that the lines +in question line up in the comparison and the previous line contains no conflict.) +This auto merge can either be run immediately after a merge starts (activate the option +"Run regular expression auto merge on merge start") or later via the merge +menu "Run Regular Expression Auto Merge". +</p><p> +Automatic merge for version control history (also called "log") is also supported. +The history automerge can either run immediately when the merge starts by activating the +option "Merge version control history on merge start" or later via the merge menu +"Automatically Solve History Conflicts". +</p><p> +Usually the version control history begins with a line containing the keyword "$Log$". +This must be matched by the "History start regular expression"-option. +<span class="application">KDiff3</span> detects which subsequent lines are in the history by analysing the leading characters +that came before the "$Log$"-keyword. If the same "leading comment"-characters also appears in the following +lines, then they are also included in the history. +</p><p> +During each check-in the VCS writes a unique line specifying version-, date- and time-information +followed by lines with user comments. +These lines form one history-entry. This history section grows with every check-in and the +most recent entries appear at the top (after the history start line). +</p><p> +When for parallel development two or more developers check-in a branch of the file then +the merge history will contain several entries that appear as conflicts during the merge +of the branches. Since merging these can become very tedious, <span class="application">KDiff3</span> offers support with two +possible strategies: Just insert the history information from both contributors at the top +or sort the history information by a user defined key. +</p><p> +The just-insert-all-entries-method is easier to configure. <span class="application">KDiff3</span> just needs a method to +detect, which lines belong to one history entry. Most VCS insert an empty line after each +history entry. If there are no other empty lines, this is a sufficient criterion for <span class="application">KDiff3</span>. +Just set an empty "History entry start regular expression". If the empty line criterion +isn't sufficient, you can specify a regular expression to detect the history entry start. +</p><p> +Note that <span class="application">KDiff3</span> will remove duplicate history entrys. If a history entry appeared several times +in the history of a input file, only one entry will remain in the output. +</p><p> +If you want to sort the history, then you have to specify how the sort key should be built. +Use parentheses in the "History entry start regular expression" to group parts of the regular +expression that should later be used for the sort key. +Then specify the "History entry start sort key order" specifying a comma "," separated list of +numbers referring to the position of the group in the regular expression. +</p><p> +Because this is not so easy to get right immediately, you are able to test and improve +the regular expressions and key-generation in a dedicated dialog by pressing the +"Test your regular expressions"-button. +</p><p>Example: Assume a history that looks like this: +<pre class="screen"> +/************************************************************************** +** HISTORY: $Log: \toms_merge_main_view\MyApplication\src\complexalgorithm.cpp $ +** +** \main\integration_branch_12 2 Apr 2001 10:45:41 tom +** Merged branch simon_branch_15. +** +** \main\henry_bugfix_branch_7\1 30 Mar 2001 19:22:05 henry +** Improved the speed for subroutine convertToMesh(). +** Fixed crash. +**************************************************************************/ +</pre> +The history start line matches the regular expression ".*\$Log.*\$.*". Then follow +the history entries. +</p><p> +The line with the "$Log$"-keyword begins with two "*" after which follows a space. +<span class="application">KDiff3</span> uses the first non-white-space string as "leading comment" and assumes that +the history ends in the first line without this leading comment. In this example the +last line ends with a string that also starts with two "*", but instead of a space +character more "*" follow. Hence this line ends the history. +</p><p> +If history sorting isn't required then the history entry start line regular expression +could look like this. (This line is split in two because it wouldn't fit otherwise.) +<pre class="screen"> +\s*\\main\\\S+\s+[0-9]+ (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) + [0-9][0-9][0-9][0-9] [0-9][0-9]:[0-9][0-9]:[0-9][0-9]\s+.* +</pre> +For details about regular expressions please see the +<a href="http://doc.trolltech.com/3.3/qregexp.html#details" target="_top">regular expression documentation by Trolltech</a>. +Note that "\s" (with lowercase "s") matches any white space and "\S" (with uppercase "S") matches any non-white-space. +In our example the history entry start contains first the version info with reg. exp. "\\main\\\S+", the date consisting of day "[0-9]+", month "(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)" and year "[0-9][0-9][0-9][0-9]", the time "[0-9][0-9]:[0-9][0-9]:[0-9][0-9]" and finally the developers login name ".*". +</p><p> +Note that the "leading comment"-characters (in the example "**") will already be removed by <span class="application">KDiff3</span> +before trying to match, hence the regular expression begins with a match for none or more white-space characters "\s*". +Because comment characters can differ in each file (e.g. C/C++ uses other comment characters than a Perl script) +<span class="application">KDiff3</span> takes care of the leading comment characters and you should not specify them in the regular expression. +</p><p> +If you require a sorted history. Then the sortkey must be calculated. For this the +relevant parts in the regular expression must be grouped by parentheses. +(The extra parentheses can also stay in if history sorting is disabled.) +<pre class="screen"> +\s*\\main\\(\S+)\s+([0-9]+) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) + ([0-9][0-9][0-9][0-9]) ([0-9][0-9]:[0-9][0-9]:[0-9][0-9])\s+(.*) +</pre> +The parentheses now contain 1. version info, 2. day, 3. month, 4. year, 5. time, 6. name. +But if we want to sort by date and time, we need to construct a key with the elements in a different order of appearance: +First the year, followed by month, day, time, version info and name. Hence the sortkey order to specify is "4,3,2,5,1,6". +</p><p> +Because month names aren't good for sorting ("Apr" would be first) <span class="application">KDiff3</span> detects in which order +the month names were given and uses that number instead ("Apr"->"04"). +And if a pure number is found it will be transformed to a 4-digit value with leading zeros for sorting. +Finally the resulting sort key for the first history entry start line will be: +<pre class="screen"> +2001 04 0002 10:45:41 integration_branch_12 tom +</pre> +</p><p> +For more information also see <a href="options.html#mergeoptions" title="Merge Settings">Merge Settings</a>. +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="interpretinginformation.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="navigation.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Comparing Files And Interpreting The Information In The Input Windows </div><div class="navRight"> Navigation And Editing</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/misc.html b/doc/en/misc.html new file mode 100644 index 0000000..34b13cf --- /dev/null +++ b/doc/en/misc.html @@ -0,0 +1,49 @@ +<html><head><title>Chapter 4. Miscellaneous Topics</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="index.html" title="The KDiff3 Handbook"><link rel="prev" href="other.html" title="Other Functions in Directory Merge Window"><link rel="next" href="kpart.html" title="Using KDiff3 as a KPart"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Miscellaneous Topics</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="other.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="kpart.html">Next</a></div><div class="navCenter"> </div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="misc"></a>Chapter 4. Miscellaneous Topics</h2></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="networktransparency"></a>Networktransparency via KIO</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2569419"></a>KIO-Slaves</h3></div></div></div><p> +KDE supports networktransparency via KIO-slaves. <span class="application">KDiff3</span> uses this +for reading input files and for scanning directories. +This means that you can specify files and directories on local and +remote resources via URLs. +</p><p> +Example: +</p><p> +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> test.cpp ftp://ftp.faraway.org/test.cpp + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> tar:/home/hacker/archive.tar.gz/dir ./dir +</pre> +</p><p>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. +</p><p> +Other KIO-slaves that are interesting are: +</p><div class="itemizedlist"><ul type="disc"><li><p>Files from the WWW (http:),</p></li><li><p>Files from the FTP (ftp:),</p></li><li><p>Encrypted file transfer (fish:, sftp:),</p></li><li><p>Windows-ressources (smb:),</p></li><li><p>Local files (file:),</p></li></ul></div><p> +Other things that are possible, but probably less useful are: +</p><div class="itemizedlist"><ul type="disc"><li><p>Man-pages (man:),</p></li><li><p>Info-pages (info:),</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2569517"></a>How To Write URLs</h3></div></div></div><p> + An URL has a different syntax compared with paths for local files and directories. + Some things should be considered: +</p><div class="itemizedlist"><ul type="disc"><li><p> + A path can be relative and can contain "." or "..". This is not possible for URLs + which are always absolute. +</p></li><li><p> + 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". +</p></li><li><p> + When URLs don't work as expected, try to open them in Konqueror first. +</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2569553"></a>Capabilities of KIO-Slaves</h3></div></div></div><p> + Networktransparency has one drawback: Not all ressources have the same cababilities. +</p><p> + Sometimes this is due to the file system of the server, sometimes due to the protocol. + Here is a short list of restrictions: +</p><div class="itemizedlist"><ul type="disc"><li><p> + Sometimes there is no support for links. +</p></li><li><p> + Or there is no way to distinguish if a link points to a file or a directory; always + assuming a file. (ftp:, sftp:). +</p></li><li><p> + Can't always determine the filesize. +</p></li><li><p> + Limited support for permissions. +</p></li><li><p> + No possibility to modify permissions or modification time, so permissions or time + of a copy will differ from the original. (See the option "Trust the size".) + (To modify permissions or modification time is only possible for local files.) +</p></li></ul></div></div></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="other.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="kpart.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Other Functions in Directory Merge Window </div><div class="navRight"> Using <span class="application">KDiff3</span> as a KPart</div><div class="navCenter"><a accesskey="u" href="index.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/navigation.html b/doc/en/navigation.html new file mode 100644 index 0000000..ccfce59 --- /dev/null +++ b/doc/en/navigation.html @@ -0,0 +1,38 @@ +<html><head><title>Navigation And Editing</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="merging.html" title="Merging And The Merge Output Editor Window"><link rel="next" href="selections.html" title="Select, Copy And Paste"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Navigation And Editing</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="merging.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="selections.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="navigation"></a>Navigation And Editing</h2></div></div></div><p> + 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><p> + You can also use the wheel mouse to scroll up and down. +</p><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 + in section <a href="merging.html#synchronise_views" title="Setting The Current Group And Synchronising Merge And Diff View Position">"Setting The Current Group And Synchronising Merge And Diff View Position"</a>). +</p><p> + The button bar also contains nine 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 <span class="application">KDiff3</span> 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". +</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="autoadvance"></a>Auto-Advance</h3></div></div></div><p> + 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, <span class="application">KDiff3</span> 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 + <span class="application">KDiff3</span> 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. +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="merging.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="selections.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Merging And The Merge Output Editor Window </div><div class="navRight"> Select, Copy And Paste</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/new.png b/doc/en/new.png Binary files differnew file mode 100644 index 0000000..df3fd25 --- /dev/null +++ b/doc/en/new.png diff --git a/doc/en/open_dialog.png b/doc/en/open_dialog.png Binary files differnew file mode 100644 index 0000000..029f8d4 --- /dev/null +++ b/doc/en/open_dialog.png diff --git a/doc/en/opendialog.html b/doc/en/opendialog.html new file mode 100644 index 0000000..58ec755 --- /dev/null +++ b/doc/en/opendialog.html @@ -0,0 +1,23 @@ +<html><head><title>Open-Dialog</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="next" href="pasteinput.html" title="Paste and Drop Input"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Open-Dialog</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="documentation.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="pasteinput.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="opendialog"></a>Open-Dialog</h2></div></div></div><p> + Since many input files must be selectable, the program has a special open dialog: +</p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="open_dialog.png"><hr></div></div><p> + 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. +</p><p> + 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 <span class="application">KDiff3</span> uses the filename from A in the + specified directories. +</p><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. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="documentation.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="pasteinput.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">File Comparison And Merge </div><div class="navRight"> Paste and Drop Input</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/options.html b/doc/en/options.html new file mode 100644 index 0000000..cff21f9 --- /dev/null +++ b/doc/en/options.html @@ -0,0 +1,138 @@ +<html><head><title>Options</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="printing.html" title="Printing"><link rel="next" href="preprocessors.html" title="Preprocessor Commands"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Options</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="printing.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="preprocessors.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="options"></a>Options</h2></div></div></div><p> + Options and the recent-file-list will be saved when you exit the program, + and reloaded when you start it. (Menu Settings->Configure <span class="application">KDiff3</span> ...) +</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2566321"></a>Font</h3></div></div></div><p> + Select a fixed width font. (On some systems this dialog will also + present variable width fonts, but you should not use them.) +</p><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Italic Font for Deltas:</em></span></span></dt><dd><p> 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.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2566353"></a>Colors</h3></div></div></div><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Foreground color:</em></span></span></dt><dd><p> Usually black. </p></dd><dt><span class="term"><span class="emphasis"><em>Background color:</em></span></span></dt><dd><p> Usually white. </p></dd><dt><span class="term"><span class="emphasis"><em>Diff Background color:</em></span></span></dt><dd><p> Usually light gray. </p></dd><dt><span class="term"><span class="emphasis"><em>Color A:</em></span></span></dt><dd><p> Usually dark blue. </p></dd><dt><span class="term"><span class="emphasis"><em>Color B:</em></span></span></dt><dd><p> Usually dark green. </p></dd><dt><span class="term"><span class="emphasis"><em>Color C:</em></span></span></dt><dd><p> Usually dark magenta. </p></dd><dt><span class="term"><span class="emphasis"><em>Conflict Color:</em></span></span></dt><dd><p> Usually red.</p></dd><dt><span class="term"><span class="emphasis"><em>Current range background color:</em></span></span></dt><dd><p> Usually light yellow.</p></dd><dt><span class="term"><span class="emphasis"><em>Current range diff background color:</em></span></span></dt><dd><p> Usually dark yellow.</p></dd><dt><span class="term"><span class="emphasis"><em>Color for manually selected diff ranges:</em></span></span></dt><dd><p> Usually orange.</p></dd><dt><span class="term"><span class="emphasis"><em>Newest file color in directory comparison:</em></span></span></dt><dd><p> Usually green.</p></dd><dt><span class="term"><span class="emphasis"><em>Oldest file color in directory comparison:</em></span></span></dt><dd><p> Usually red.</p></dd><dt><span class="term"><span class="emphasis"><em>Middle age file color in directory comparison:</em></span></span></dt><dd><p> Usually dark yellow.</p></dd><dt><span class="term"><span class="emphasis"><em>Color for missing files in directory comparison:</em></span></span></dt><dd><p> Usually black.</p></dd></dl></div><p> + Changing the colors for directory comparison will be effective only when starting the next directory comparison. +</p><p> + 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2566534"></a>Editor Settings</h3></div></div></div><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Tab inserts spaces:</em></span></span></dt><dd><p> If this is disabled and you press the + tabulator key, a tab-character is inserted, otherwise the appropriate + amount of characters is inserted.</p></dd><dt><span class="term"><span class="emphasis"><em> Tab size:</em></span></span></dt><dd><p> Can be adjusted for your specific needs. Default is 8. </p></dd><dt><span class="term"><span class="emphasis"><em> Auto indentation:</em></span></span></dt><dd><p> When pressing Enter or Return the indentation + of the previous line is used for the new line. </p></dd><dt><span class="term"><span class="emphasis"><em> Auto copy selection:</em></span></span></dt><dd><p> Every selection is immediately copied + to the clipboard when active and you needn't explicitely copy it. </p></dd><dt><span class="term"><span class="emphasis"><em> Line end style:</em></span></span></dt><dd><p> When saving you can select what line + end style you prefer. The default setting is the common choice for the used operating system. </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="diffoptions"></a>Diff Settings</h3></div></div></div><p> + When comparing files, <span class="application">KDiff3</span> 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. +</p><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Preserve Carriage Return:</em></span></span></dt><dd><p> 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 <span class="application">KDiff3</span> 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.</p></dd><dt><span class="term"><span class="emphasis"><em>Ignore numbers:</em></span></span></dt><dd><p> 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. + </p></dd><dt><span class="term"><span class="emphasis"><em>Ignore C/C++ comments:</em></span></span></dt><dd><p> Default is off. + Changes in comments will be treated like changes in white space. + </p></dd><dt><span class="term"><span class="emphasis"><em>Ignore case:</em></span></span></dt><dd><p> Default is off. + Case-differences of characters (like 'A' vs. 'a') will be treated like changes in white space. + </p></dd><dt><span class="term"><span class="emphasis"><em>Preprocessor-Command:</em></span></span></dt><dd><p> + See <a href="preprocessors.html" title="Preprocessor Commands">next section</a>. + </p></dd><dt><span class="term"><span class="emphasis"><em>Line-Matching Preprocessor-Command:</em></span></span></dt><dd><p> + See <a href="preprocessors.html" title="Preprocessor Commands">next section</a>. + </p></dd><dt><span class="term"><span class="emphasis"><em>Try Hard:</em></span></span></dt><dd><p> + Try hard to find an even smaller delta. (Default is on.) This will probably + be effective for complicated and big files. And slow for very big files. + </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mergeoptions"></a>Merge Settings</h3></div></div></div><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Auto Advance Delay (ms):</em></span></span></dt><dd><p> When in auto-advance-mode this setting specifies + how long to show the result of the selection before jumping to the next unsolved + conflict. + </p></dd><dt><span class="term"><span class="emphasis"><em>White space 2/3-file merge default:</em></span></span></dt><dd><p> + Automatically solve all white-space conflict by choosing the specified file. + (Default is manual choice.) Useful if white space really isn't important in many files. + If you need this only occasionally better use "Choose A/B/C For All Unsolved Whitespace Conflicts" + in the merge menu. Note that if you enable either "Ignore numbers" or "Ignore C/C++ comments" + then this auto-choice also applies for conflicts in numbers or comments. + </p></dd><dt><span class="term"><span class="emphasis"><em>Auto merge regular expression:</em></span></span></dt><dd><p> + Regular expression for lines where <span class="application">KDiff3</span> should automatically choose one source. See also <a href="merging.html#vcskeywordsmergesupport" title="Automatic Merge of Version Control Keywords and History (Log)">Automatic Merge ...</a> + </p></dd><dt><span class="term"><span class="emphasis"><em>Run regular expression auto merge on merge start:</em></span></span></dt><dd><p> + If activated <span class="application">KDiff3</span> runs the automatic merge using the "Auto merge regular expression" when a merge is started. + </p></dd><dt><span class="term"><span class="emphasis"><em>History start regular expression:</em></span></span></dt><dd><p> + Regular expression for the start of the merge history entry. + Usually this line contains the "$Log$"-keyword. + Default value: ".*\$Log.*\$.*" + </p></dd><dt><span class="term"><span class="emphasis"><em>History entry start regular expression:</em></span></span></dt><dd><p> + A merge history entry consists of several lines. + Specify the regular expression to detect the first line (without the leading comment). + Use parentheses to group the keys you want to use for sorting. + If left empty, then <span class="application">KDiff3</span> assumes that empty lines separate history entries. + See also <a href="merging.html#vcskeywordsmergesupport" title="Automatic Merge of Version Control Keywords and History (Log)">Automatic Merge ...</a> + </p></dd><dt><span class="term"><span class="emphasis"><em>History merge sorting:</em></span></span></dt><dd><p> + Enable version control history sorting. + </p></dd><dt><span class="term"><span class="emphasis"><em>History entry start sort key order:</em></span></span></dt><dd><p> + Each parentheses used in the regular expression for the history start entry + groups a key that can be used for sorting. + Specify the list of keys (that are numbered in order of occurrence + starting with 1) using ',' as separator (e.g. "4,5,6,1,2,3,7"). + If left empty, then no sorting will be done. + See also <a href="merging.html#vcskeywordsmergesupport" title="Automatic Merge of Version Control Keywords and History (Log)">Automatic Merge ...</a> + </p></dd><dt><span class="term"><span class="emphasis"><em>Merge version control history on merge start:</em></span></span></dt><dd><p> + If activated <span class="application">KDiff3</span> runs the automatic history merging using aforementioned options when a merge is started. + </p></dd><dt><span class="term"><span class="emphasis"><em>Max number of history entries:</em></span></span></dt><dd><p> + <span class="application">KDiff3</span> truncates the history list after the specified number of entries. Use -1 to avoid truncation. (Default is -1). + </p></dd><dt><span class="term"><span class="emphasis"><em>Test your regular expressions</em></span></span></dt><dd><p> + This button shows a dialog that allows you to improve and test the regular expressions above. + Just copy the respective data from your files into the example lines. The "Match results" + will immediately show whether the match succeeds or not. + The "Sort key result" will display the key used for history merge sorting. + </p></dd><dt><span class="term"><span class="emphasis"><em>Irrelevant merge command:</em></span></span></dt><dd><p> + Specify a command of your own that should be called when <span class="application">KDiff3</span> detects + that for a three file merge the file from B doesn't contribute any + relevant data that isn't already contained in the file from C. + The command is called with the three filenames as parameters. + Data matched by the "Auto merge regular expression" or in the + history isn't considered relevant. + </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2566994"></a>Directory Merge</h3></div></div></div><p> + These options are concerned with scanning the directory and handling the + merge: See the <a href="dirmergeoptions.html" title="Options for Comparing and Merging Directories">Directory Comparison/Merge + Docs</a> for details. +</p><p> +Yet there is one option here that is also relevant for saving single files: +</p><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Backup files:</em></span></span></dt><dd><p> 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. + </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2567038"></a>Regional and Language Options</h3></div></div></div><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Language:</em></span></span></dt><dd><p>Adjust the language of the user interface. Changing this option doesn't affect the running program. You have to exit and restart <span class="application">KDiff3</span> so that the language is changed. (This option is not available in the KDE version of <span class="application">KDiff3</span> because the language is adjustable in the global KDE settings.) + </p></dd><dt><span class="term"><span class="emphasis"><em>Use the same encoding for everything:</em></span></span></dt><dd><p> The following encoding options can be adjusted separately for each item or if this option is true, all values will take the first value. + </p></dd><dt><span class="term"><span class="emphasis"><em>Local Encoding:</em></span></span></dt><dd><p>Above the codec-selectors appears a note that tells you what the local encoding is. (This is not adjustable but for your information just in case you don't know your local encoding, but need to select it.) + </p></dd><dt><span class="term"><span class="emphasis"><em>File Encoding for A/B/C:</em></span></span></dt><dd><p> Adjust the file encoding for input files. This has an effect on how the special characters are interpreted. Since you can adjust each codec separately you can even compare and merge files that were saved using different codecs. + </p></dd><dt><span class="term"><span class="emphasis"><em>File Encoding for Merge Output and Saving:</em></span></span></dt><dd><p> When you have edited a file, then you can adjust which encoding will be used when saving to disk. + </p></dd><dt><span class="term"><span class="emphasis"><em>File Encoding for Preprocessor Files:</em></span></span></dt><dd><p>When you define preprocessors then they might not be able to operate on your codec. (e.g.: Your files are 16-bit-unicode and your preprocessor can only take 8-bit-ascii.) With this option you can define the encoding of preprocessor output. + </p></dd><dt><span class="term"><span class="emphasis"><em>Right To Left Language:</em></span></span></dt><dd><p>Some languages are written right to left. When this option is enabled, <span class="application">KDiff3</span> draws the text from right to left in the diff input windows and in the merge output window. Note that if you start <span class="application">KDiff3</span> with the command line option "--reverse" then all layouting will be done right to left too. (This is a feature provided by Qt.) This documentation was written assuming that "Right To Left Language" or reverse layout are disabled. So some references to "left" or "right" must be replaced by their respective counterpart if you use these options. + </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2567171"></a>Miscellaneous</h3></div></div></div><p>(These options and actions are available in menus or the buttonbar.)</p><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Show line numbers:</em></span></span></dt><dd><p> You can select if line numbers should be + shown for the input files.</p></dd><dt><span class="term"><span class="emphasis"><em>Show space and tabulator characters for differences:</em></span></span></dt><dd><p> Sometimes + the visible spaces and tabs are disturbing. You can turn this off.</p></dd><dt><span class="term"><span class="emphasis"><em>Show white space:</em></span></span></dt><dd><p> Turn this off to suppress + any highlighting of white-space-only changes in the text or overview-columns. + (Note that this also applies to changes in numbers or comments if the options "Ignore numbers" + or "Ignore C/C++ comments" are active.)</p></dd><dt><span class="term"><span class="emphasis"><em>Overview options:</em></span></span></dt><dd><p> + These choices are only available when you compare three files. In normal mode all + differences are shown in one color-coded overview-column. But sometimes you are + especially interested in the differences between only two of these three files. + Selecting "A vs. B", "A vs. C" or "B vs. C"-overview will show a second overview + column with the required information next to the normal overview. + </p></dd><dt><span class="term"><span class="emphasis"><em>Word wrap diff windows:</em></span></span></dt><dd><p> + Wrap lines when their length would exceed the width of a window. + </p></dd><dt><span class="term"><span class="emphasis"><em>Show Window A/B/C:</em></span></span></dt><dd><p> 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.)</p></dd><dt><span class="term"><span class="emphasis"><em>Toggle Split Orientation:</em></span></span></dt><dd><p> + 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.) + </p></dd><dt><span class="term"><span class="emphasis"><em>Start a merge quickly:</em></span></span></dt><dd><p> + Sometimes you are viewing the deltas and decide to merge. + <span class="inlinemediaobject"><img src="merge_current.png"></span> + "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.)</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="shortcuts"></a>Configuring Keyboard-Shortcuts</h3></div></div></div><p> + Currently only the KDE-version supports user-configurable keyboard-shortcuts. + (Menu Settings->Configure Shortcuts...) +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="printing.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="preprocessors.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Printing </div><div class="navRight"> Preprocessor Commands</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/other.html b/doc/en/other.html new file mode 100644 index 0000000..8919bd5 --- /dev/null +++ b/doc/en/other.html @@ -0,0 +1,33 @@ +<html><head><title>Other Functions in Directory Merge Window</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3"><link rel="prev" href="dirmergeoptions.html" title="Options for Comparing and Merging Directories"><link rel="next" href="misc.html" title="Chapter 4. Miscellaneous Topics"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Other Functions in Directory Merge Window</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="dirmergeoptions.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="misc.html">Next</a></div><div class="navCenter">Directory Comparison and Merge with <span class="application">KDiff3</span></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="other"></a>Other Functions in Directory Merge Window</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2569323"></a>Split/Full Screen Mode</h3></div></div></div><p> + 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. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2569341"></a>Comparing or Merging a Single File</h3></div></div></div><p> + 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 by selecting it and + choosing "Merge current file" in the "Merge"-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. +</p><p> + But note that this status information will be lost when you rerun a directory + scan: "Directory"-menu: "Rescan" +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2569364"></a>Comparing or Merging Files with Different Names</h3></div></div></div><p> + Sometimes you need to compare or merge files with different names (e.g. the current + file and the backup in the same folder). +</p><p> + Select the exact file by clicking onto the icon in the column A, B or C. The first + file selected thus will be marked with an "A", the second and third with "B" and "C" + regardless on what column they are in. Only up to three files can be chosen like this. +</p><p> + Proceed by choosing "Compare Explicitely Selected Files" or "Merge Explicitely + Selected Files" from the "Directory"-menu. For your convenience these menu entries + also appear as context menu when you right-click the last selected file. +</p><p> + The comparison or merge of a file will happen in the same window. + If this method is used for directories a new window will be opened. +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="dirmergeoptions.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="misc.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Options for Comparing and Merging Directories </div><div class="navRight"> Miscellaneous Topics</div><div class="navCenter"><a accesskey="u" href="dirmerge.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/pasteinput.html b/doc/en/pasteinput.html new file mode 100644 index 0000000..8d913ba --- /dev/null +++ b/doc/en/pasteinput.html @@ -0,0 +1,20 @@ +<html><head><title>Paste and Drop Input</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="opendialog.html" title="Open-Dialog"><link rel="next" href="interpretinginformation.html" title="Comparing Files And Interpreting The Information In The Input Windows"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Paste and Drop Input</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="opendialog.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="interpretinginformation.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pasteinput"></a>Paste and Drop Input</h2></div></div></div><p> + Sometimes you want to compare parts of a text that is not an own file. <span class="application">KDiff3</span> 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". +</p><p> + 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. +</p><p> + 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. +</p><p> + Note: Currently you cannot drag anything from <span class="application">KDiff3</span>. Only dropping in the diff input + is supported. +</p><p> + 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. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="opendialog.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="interpretinginformation.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Open-Dialog </div><div class="navRight"> Comparing Files And Interpreting The Information In The Input Windows</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/preprocessors.html b/doc/en/preprocessors.html new file mode 100644 index 0000000..427f717 --- /dev/null +++ b/doc/en/preprocessors.html @@ -0,0 +1,202 @@ +<html><head><title>Preprocessor Commands</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="options.html" title="Options"><link rel="next" href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Preprocessor Commands</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="options.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dirmerge.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="preprocessors"></a>Preprocessor Commands</h2></div></div></div><p> +<span class="application">KDiff3</span> supports two preprocessor options. +</p><p> +<div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Preprocessor-Command:</em></span></span></dt><dd><p> + 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. + </p></dd><dt><span class="term"><span class="emphasis"><em>Line-Matching Preprocessor-Command:</em></span></span></dt><dd><p> + 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. + </p></dd></dl></div> +</p><p> +The idea is to allow the user greater flexibility while configuring the diff-result. +But this requires an external program, and many users don't want to write one themselves. +The good news is that very often <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span> +will do the job. +</p><p>Example: Simple testcase: Consider file a.txt (6 lines): +<pre class="screen"> + aa + ba + ca + da + ea + fa +</pre> +And file b.txt (3 lines): +<pre class="screen"> + cg + dg + eg +</pre> +Without a preprocessor the following lines would be placed next to each other: +<pre class="screen"> + aa - cg + ba - dg + ca - eg + da + ea + fa +</pre> +This is probably not wanted since the first letter contains the actually interesting information. +To help the matching algorithm to ignore the second letter we can use a line matching preprocessor +command, that replaces 'g' with 'a': +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/g/a/' +</pre> +With this command the result of the comparison would be: +<pre class="screen"> + aa + ba + ca - cg + da - dg + ea - eg + fa +</pre> +Internally the matching algorithm sees the files after running the line matching preprocessor, +but on the screen the file is unchanged. (The normal preprocessor would change the data also on +the screen.) +</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sedbasics"></a><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> Basics</h3></div></div></div><p> +This section only introduces some very basic features of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>. For more +information see <a href="info:/sed" target="_top">info:/sed</a> or +<a href="http://www.gnu.org/software/sed/manual/html_mono/sed.html" target="_top"> +http://www.gnu.org/software/sed/manual/html_mono/sed.html</a>. +A precompiled version for Windows can be found at <a href="http://unxutils.sourceforge.net" target="_top"> +http://unxutils.sourceforge.net</a>. +Note that the following examples assume that the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>-command is in some +directory in the PATH-environment variable. If this is not the case, you have to specify the full absolute +path for the command. +</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Also note that the following examples use the single quotation mark (') which won't work for Windows. +On Windows you should use the double quotation marks (") instead.</p></div><p> +In this context only the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>-substitute-command is used: +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>REGEXP</code></em></span>/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>REPLACEMENT</code></em></span>/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>FLAGS</code></em></span>' +</pre> +Before you use a new command within <span class="application">KDiff3</span>, you should first test it in a console. +Here the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">echo</strong></span></span>-command is useful. Example: +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">echo</strong></span></span> abrakadabra | <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/a/o/' + -> obrakadabra +</pre> +This example shows a very simple sed-command that replaces the first occurance +of "a" with "o". If you want to replace all occurances then you need the "g"-flag: +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">echo</strong></span></span> abrakadabra | <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/a/o/g' + -> obrokodobro +</pre> +The "|"-symbol is the pipe-command that transfers the output of the previous +command to the input of the following command. If you want to test with a longer file +then you can use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">cat</strong></span></span> on Unix-like systems or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">type</strong></span></span> +on Windows-like systems. <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> will do the substitution for each line. +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">cat</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>filename</code></em></span> | <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>options</code></em></span> +</pre> +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sedforkdiff3"></a>Examples For <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>-Use In <span class="application">KDiff3</span></h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567628"></a>Ignoring Other Types Of Comments</h4></div></div></div><p> +Currently <span class="application">KDiff3</span> understands only C/C++ comments. Using the +Line-Matching-Preprocessor-Command you can also ignore +other types of comments, by converting them into C/C++-comments. + +Example: To ignore comments starting with "#", you would like to convert them +to "//". Note that you also must enable the "Ignore C/C++-Comments" option to get +an effect. An appropriate Line-Matching-Preprocessor-Command would be: + +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/#/\/\//' +</pre> +Since for <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> the "/"-character has a special meaning, it is necessary to place the +"\"-character before each "/" in the replacement-string. Sometimes the "\" is required +to add or remove a special meaning of certain characters. The single quotation marks (') before +and after the substitution-command are important now, because otherwise the shell will +try to interpret some special characters like '#', '$' or '\' before passing them to +<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>. <span class="emphasis"><em>Note that on Windows you will need the double quotation marks (") here. Windows +substitutes other characters like '%', so you might have to experiment a little bit.</em></span> +</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567680"></a>Caseinsensitive Diff</h4></div></div></div><p> +Use the following Line-Matching-Preprocessor-Command to convert all input to uppercase: +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/\(.*\)/\U\1/' +</pre> +Here the ".*" is a regular expression that matches any string and in this context matches +all characters in the line. +The "\1" in the replacement string refers to the matched text within the first pair of "\(" and "\)". +The "\U" converts the inserted text to uppercase. +</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567704"></a>Ignoring Version Control Keywords</h4></div></div></div><p> +CVS and other version control systems use several keywords to insert automatically +generated strings (<a href="info:/cvs/Keyword%20substitution" target="_top">info:/cvs/Keyword substitution</a>). +All of them follow the pattern "$KEYWORD generated text$". We now need a +Line-Matching-Preprocessor-Command that removes only the generated text: +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/\$\(Revision\|Author\|Log\|Header\|Date\).*\$/\$\1\$/' +</pre> +The "\|" separates the possible keywords. You might want to modify this list +according to your needs. +The "\" before the "$" is necessary because otherwise the "$" matches the end of the line. +</p><p> +While experimenting with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> you might come to understand and even like +these regular expressions. They are useful because there are many other programs that also +support similar things. +</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567750"></a>Ignoring Numbers</h4></div></div></div><p> +Ignoring numbers actually is a built-in option. But as another example, this is how +it would look as a Line-Matching-Preprocessor-command. +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/[0123456789.-]//g' +</pre> +Any character within '[' and ']' is a match and will be replaced with nothing. +</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567772"></a>Ignoring Certain Columns</h4></div></div></div><p> +Sometimes a text is very strictly formatted, and contains columns that you always want to ignore, while there are +other columns you want to preserve for analysis. In the following example the first five columns (characters) are +ignored, the next ten columns are preserved, then again five columns are ignored and the rest of the line is preserved. +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/.....\(..........\).....\(.*\)/\1\2/' +</pre> +Each dot '.' matches any single character. The "\1" and "\2" in the replacement string refer to the matched text within the first +and second pair of "\(" and "\)" denoting the text to be preserved. +</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567800"></a>Combining Several Substitutions</h4></div></div></div><p> +Sometimes you want to apply several substitutions at once. You can then use the +semicolon ';' to separate these from each other. Example: +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">echo</strong></span></span> abrakadabra | <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/a/o/g;s/\(.*\)/\U\1/' + -> OBROKODOBRO +</pre> +</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567827"></a>Using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span> instead of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span></h4></div></div></div><p> +Instead of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> you might want to use something else like +<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span>. +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span> -p -e 's/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>REGEXP</code></em></span>/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>REPLACEMENT</code></em></span>/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>FLAGS</code></em></span>' +</pre> +But some details are different in <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span>. Note that where +<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> needed "\(" and "\)" <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span> +requires the simpler "(" and ")" without preceding '\'. Example: +<pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/\(.*\)/\U\1/' + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span> -p -e 's/(.*)/\U\1/' +</pre> +</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2567900"></a>Order Of Preprocessor Execution</h3></div></div></div><p> +The data is piped through all internal and external preprocessors in the +following order: +</p><div class="itemizedlist"><ul type="disc"><li><p>Normal preprocessor,</p></li><li><p>Line-Matching-Preprocessor,</p></li><li><p>Ignore case (conversion to uppercase),</p></li><li><p>Detection of C/C++ comments,</p></li><li><p>Ignore numbers,</p></li><li><p>Ignore white space</p></li></ul></div><p> +The data after the normal preprocessor will be preserved for display and merging. The +other operations only modify the data that the line-matching-diff-algorithm sees. +</p><p> +In the rare cases where you use a normal preprocessor note that +the line-matching-preprocessor sees the output of the normal preprocessor as input. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2567963"></a>Warning</h3></div></div></div><p> +The preprocessor-commands are often very useful, but as with any option that modifies +your texts or hides away certain differences automatically, you might accidentally overlook +certain differences and in the worst case destroy important data. +</p><p> +For this reason during a merge if a normal preprocessor-command is being used <span class="application">KDiff3</span> +will tell you so and ask you if it should be disabled or not. +But it won't warn you if a Line-Matching-Preprocessor-command is active. The merge will not complete until +all conflicts are solved. If you disabled "Show White Space" then the differences that +were removed with the Line-Matching-Preprocessor-command will also be invisible. If the +Save-button remains disabled during a merge (because of remaining conflicts), make sure to enable +"Show White Space". If you don't wan't to merge these less important differences manually +you can select "Choose [A|B|C] For All Unsolved White space Conflicts" in the Merge-menu. +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="options.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dirmerge.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Options </div><div class="navRight"> Directory Comparison and Merge with <span class="application">KDiff3</span></div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/printing.html b/doc/en/printing.html new file mode 100644 index 0000000..bca62f3 --- /dev/null +++ b/doc/en/printing.html @@ -0,0 +1,20 @@ +<html><head><title>Printing</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="find.html" title="Finding Strings"><link rel="next" href="options.html" title="Options"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Printing</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="find.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="options.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="printing"></a>Printing</h2></div></div></div><p> + <span class="application">KDiff3</span> supports printing for textfile differences. The "Print..."-command (Ctrl-P) + in the File-menu opens a dialog that allows you to select the printer and to adjust + other options. +</p><p> + There are several possibilities to adjust the range. Due to different printing + dialogs on different operating systems, the method to achieve certain range selections varies. +</p><div class="variablelist"><dl><dt><span class="term">All:</span></dt><dd><p>Print everything.</p></dd><dt><span class="term">Current:</span></dt><dd><p>Print a page starting at the first visible line in the window. + (On systems without this option this can be achived by specifying page number 10000 for printing.)</p></dd><dt><span class="term">Selection:</span></dt><dd><p> + Before choosing to print select text with the mouse (like for copy and paste) + in one of the diff input windows to define the start and end line. If no text + in one of the diff input windows was selected, then this won't be an available + choice. (On systems without this option this can be achived by specifying page + number 9999 for printing.)</p></dd><dt><span class="term">Range:</span></dt><dd><p>Specify the first and last page. + </p></dd></dl></div><p> + Other important options for printing will be taken from the normal options: +</p><div class="itemizedlist"><ul type="disc"><li><p>Font, font size</p></li><li><p>Show line numbers</p></li><li><p>Word wrap</p></li><li><p>Colors</p></li><li><p>etc.</p></li></ul></div><p> + Landscape formatting is also recommended for printing. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="find.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="options.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Finding Strings </div><div class="navRight"> Options</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/requirements.html b/doc/en/requirements.html new file mode 100644 index 0000000..983137c --- /dev/null +++ b/doc/en/requirements.html @@ -0,0 +1,10 @@ +<html><head><title>Requirements</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="installation.html" title="Appendix A. Installation"><link rel="prev" href="installation.html" title="Appendix A. Installation"><link rel="next" href="compilation.html" title="Compilation and Installation"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Requirements</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="installation.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="compilation.html">Next</a></div><div class="navCenter">Installation</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="requirements"></a>Requirements</h2></div></div></div><p> + In order to successfully use all features of <span class="application">KDiff3</span>, you need <span class="acronym">KDE</span> >3.1. +</p><p> + For information about how to run <span class="application">KDiff3</span> on other platforms without KDE please see the + <a href="http://kdiff3.sourceforge.net" target="_top">homepage</a>. +</p><p> +You can find a list of changes at <a href="http://kdiff3.sourceforge.net/ChangeLog" target="_top">http://kdiff3.sourceforge.net/ChangeLog</a> +or in the "ChangeLog"-file of the source package. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="installation.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="compilation.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Installation </div><div class="navRight"> Compilation and Installation</div><div class="navCenter"><a accesskey="u" href="installation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/saving.html b/doc/en/saving.html new file mode 100644 index 0000000..74d24e3 --- /dev/null +++ b/doc/en/saving.html @@ -0,0 +1,16 @@ +<html><head><title>Saving</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="selections.html" title="Select, Copy And Paste"><link rel="next" href="find.html" title="Finding Strings"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Saving</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="selections.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="find.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="saving"></a>Saving</h2></div></div></div><p> + 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 <span class="application">KDiff3</span> will ask if you want to save, cancel or proceed + without saving. (<span class="application">KDiff3</span> does not catch any signals. So if you "kill" <span class="application">KDiff3</span> + then your data will be lost.) +</p><p> + 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". <span class="application">KDiff3</span> does not preserve the line-endings of the input files, which + also means that you shouldn't use <span class="application">KDiff3</span> with binary files. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="selections.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="find.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Select, Copy And Paste </div><div class="navRight"> Finding Strings</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/screenshot_diff.png b/doc/en/screenshot_diff.png Binary files differnew file mode 100644 index 0000000..d2865d5 --- /dev/null +++ b/doc/en/screenshot_diff.png diff --git a/doc/en/screenshot_merge.png b/doc/en/screenshot_merge.png Binary files differnew file mode 100644 index 0000000..1eb935b --- /dev/null +++ b/doc/en/screenshot_merge.png diff --git a/doc/en/screenshots.html b/doc/en/screenshots.html new file mode 100644 index 0000000..badb664 --- /dev/null +++ b/doc/en/screenshots.html @@ -0,0 +1,15 @@ +<html><head><title>Screenshots and Features</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="introduction.html" title="Chapter 1. Introduction"><link rel="prev" href="introduction.html" title="Chapter 1. Introduction"><link rel="next" href="features.html" title="More Features"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Screenshots and Features</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="introduction.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="features.html">Next</a></div><div class="navCenter">Introduction</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="screenshots"></a>Screenshots and Features</h2></div></div></div><p>This screenshot shows the difference between two text files</p><p>(Using an early version of <span class="application">KDiff3</span>):</p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="screenshot_diff.png"><hr></div></div><p> + 3-way-merging is fully supported. This is useful if two people change code independently. + The original file (the base) is used to help <span class="application">KDiff3</span> 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: +</p><p> +<div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="screenshot_merge.png"><hr></div></div> +</p><p><a name="dirmergebigscreenshot"></a><span class="application">KDiff3</span> also helps you to compare and merge complete directories. +This screenshot shows <span class="application">KDiff3</span> during a directory merge: +</p><p> +<div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><hr><img src="dirmergebig.png"><hr></div></div> +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="introduction.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="features.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Introduction </div><div class="navRight"> More Features</div><div class="navCenter"><a accesskey="u" href="introduction.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/selections.html b/doc/en/selections.html new file mode 100644 index 0000000..32cd75e --- /dev/null +++ b/doc/en/selections.html @@ -0,0 +1,34 @@ +<html><head><title>Select, Copy And Paste</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="navigation.html" title="Navigation And Editing"><link rel="next" href="saving.html" title="Saving"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Select, Copy And Paste</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="navigation.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="saving.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="selections"></a>Select, Copy And Paste</h2></div></div></div><p> + 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><p> + If the selection exceeds the visible range you can move the mouse over the + window borders which causes <span class="application">KDiff3</span> to scroll in that direction. +</p><p> + For very large selections you can also use the navigation keys while holding down + the mouse. E.g. use page up and page down to quickly go to a certain position. At the + end position release the mouse button. +</p><p> + In order to select everything in the current window use menu "Edit"->"Select All" (Ctrl-A). +</p><p> + 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. +</p><p> + "Cut" (Ctrl-X or Shift-Delete) copies to the clipboard and deletes the + selected text. +</p><p> + "Paste" (Ctrl-V or Shift-Insert) inserts the text in the clipboard at the + cursorposition or over the current selection. + If you paste to either diff input window the contents of the clipboard will + be shown in that window and the comparison will restart immediately. This is + useful if you want to quickly grab a piece of text from somewhere and + compare it with something else without first creating files. +</p></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="navigation.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="saving.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Navigation And Editing </div><div class="navRight"> Saving</div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/startingdirmerge.html b/doc/en/startingdirmerge.html new file mode 100644 index 0000000..c737748 --- /dev/null +++ b/doc/en/startingdirmerge.html @@ -0,0 +1,22 @@ +<html><head><title>Starting Directory Comparison Or Merge</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3"><link rel="prev" href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3"><link rel="next" href="dirmergevisible.html" title="Directory Merge Visible Information"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Starting Directory Comparison Or Merge</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="dirmerge.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dirmergevisible.html">Next</a></div><div class="navCenter">Directory Comparison and Merge with <span class="application">KDiff3</span></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="startingdirmerge"></a>Starting Directory Comparison Or Merge</h2></div></div></div><p> + 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. +</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2568158"></a>Compare/Merge two directories: </h3></div></div></div><pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1 dir2</code></em></span> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1 dir2</code></em></span> -o <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>destdir</code></em></span> +</pre><p> + If no destination directory is specified, then <span class="application">KDiff3</span> will use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir2</code></em></span>. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2568202"></a>Compare/Merge three directories: </h3></div></div></div><pre class="screen"> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1 dir2 dir3</code></em></span> + <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">kdiff3</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1 dir2 dir3</code></em></span> -o <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>destdir</code></em></span> +</pre><p> + When three directories are merged then <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir1</code></em></span> + is used as the base for the merge. + If no destination directory is specified, then <span class="application">KDiff3</span> will use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>dir3</code></em></span> + as the destination directory for the merge. +</p><p> + Note that only the comparison starts automatically, not the merge. For this you first must + select a menu entry or the key F7. (More details later.) +</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="dirmerge.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dirmergevisible.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Directory Comparison and Merge with <span class="application">KDiff3</span> </div><div class="navRight"> Directory Merge Visible Information</div><div class="navCenter"><a accesskey="u" href="dirmerge.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br> + Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>
\ No newline at end of file diff --git a/doc/en/triple_diff.png b/doc/en/triple_diff.png Binary files differnew file mode 100644 index 0000000..c635d14 --- /dev/null +++ b/doc/en/triple_diff.png diff --git a/doc/en/white_space.png b/doc/en/white_space.png Binary files differnew file mode 100644 index 0000000..e40a1c7 --- /dev/null +++ b/doc/en/white_space.png |
