diff options
Diffstat (limited to 'doc')
146 files changed, 15538 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 00000000..6812bd2d --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +SUBDIRS = $(AUTODIRS) + diff --git a/doc/cervisia/Makefile.am b/doc/cervisia/Makefile.am new file mode 100644 index 00000000..171f575c --- /dev/null +++ b/doc/cervisia/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/cervisia/annotate.png b/doc/cervisia/annotate.png Binary files differnew file mode 100644 index 00000000..279c33f5 --- /dev/null +++ b/doc/cervisia/annotate.png diff --git a/doc/cervisia/checkout.png b/doc/cervisia/checkout.png Binary files differnew file mode 100644 index 00000000..35e2836e --- /dev/null +++ b/doc/cervisia/checkout.png diff --git a/doc/cervisia/commit.png b/doc/cervisia/commit.png Binary files differnew file mode 100644 index 00000000..dc72147f --- /dev/null +++ b/doc/cervisia/commit.png diff --git a/doc/cervisia/diff.png b/doc/cervisia/diff.png Binary files differnew file mode 100644 index 00000000..3d3c7903 --- /dev/null +++ b/doc/cervisia/diff.png diff --git a/doc/cervisia/history.png b/doc/cervisia/history.png Binary files differnew file mode 100644 index 00000000..81da16fd --- /dev/null +++ b/doc/cervisia/history.png diff --git a/doc/cervisia/import.png b/doc/cervisia/import.png Binary files differnew file mode 100644 index 00000000..46710567 --- /dev/null +++ b/doc/cervisia/import.png diff --git a/doc/cervisia/index.docbook b/doc/cervisia/index.docbook new file mode 100644 index 00000000..66e45dd9 --- /dev/null +++ b/doc/cervisia/index.docbook @@ -0,0 +1,3224 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&cervisia;"> + <!ENTITY package "kdesdk"> + <!ENTITY ssh "<command>ssh</command>"> + <!ENTITY rsh "<command>rsh</command>"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> <!-- Change language only here --> + <!ENTITY CVS "<application>CVS</application>"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>&cervisia; Manual</title> +<authorgroup> +<author> +<firstname>Bernd</firstname><surname>Gehrmann</surname> +<affiliation><address><email>bernd@mail.berlios.de</email></address></affiliation> +</author> +<author> +<firstname>Carlos</firstname><surname>Woelz</surname> +<affiliation><address><email>carloswoelz@imap-mail.com</email></address></affiliation> +</author> + + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>1999</year> +<year>2000</year> +<year>2001</year> +<year>2002</year> +<holder>Bernd Gehrmann</holder> +</copyright> + +<copyright> +<year>2004</year> +<holder>Carlos Woelz</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2004-06-06</date> +<releaseinfo>2.01.90</releaseinfo> + +<abstract> +<para>&cervisia; provides a graphical view of &CVS;.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdesdk</keyword> +<keyword>Cervisia</keyword> +<keyword>CVS</keyword> +<keyword>version control</keyword> +<keyword>revision control</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +<ulink url="http://www.kde.org/apps/cervisia/">&cervisia;</ulink> is a +user friendly version control system front-end. The aim is to support &CVS; and +other version control system programs in a unified interface, featuring conflict +resolution, difference and history viewers, status for the working copy files, +and support for most version control functions. You can get &cervisia; +by building the kdesdk module or installing the kdesdk package provided by your +distribution. Currently, only &CVS; is supported, but other version control +systems may be integrated in the future. +</para> + +<para> +A version control system is a tool to record, manage, and distribute +different versions of files. &CVS; is a version control system. It allows you +to share your modifications easily, as each of the contributors can work on their +local copy at the same time, without fear of overwriting each others' +modifications. It allows the recovery of past versions (useful for tracking +bugs), the creation of branches (for experimental development or for releases +of code) and more. +</para> + +<para> +The main <firstterm>repository</firstterm> usually holds a collaborative +project (commercial or not), but you can take advantage of the nice revision +control features offered by &CVS; even for a project developed exclusively by +you. It is easy to set up a local repository, and you will gain the ability to +track changes that caused bugs, revert changes, avoid accidental loss of +information, &etc;. +</para> + +<para> +The repository holds the project files, and every contributor keeps their +own local copy, named <firstterm>working copy</firstterm> or +<firstterm>sandbox</firstterm>; one can then add their modifications to the main +repository (a process called "committing") and/or update their own +copy to reflect recent changes made by other contributors. +</para> + +</chapter> + +<chapter id="getting-started"> +<title>Getting Started</title> + +<sect1 id="accessing-repository"> +<title>Accessing The Repository</title> + +<para> +In this section, we show how to use the basic version control system +functionality using &cervisia; to checkout modules from the +repository and work with them. To do that, you must have access to the +repository as a client, meaning that someone (probably the administrator of +the &CVS; repository) gave you an account on the server machine. Alternatively, +you can easily create a local repository for your own project. +</para> + +<tip><para> +If you plan to develop a complex project, it is a good idea to use the +&CVS; features, even if you are the only developer. You can make all changes in +the working copy, and use &cervisia; (or any other &CVS; tool) to update and +commit. This way, you will gain the ability to track changes that caused bugs, +revert changes, avoid accidental loss of information, &etc;. Using &cervisia;, it +is simple to create a local repository. +</para> + +<procedure> +<title>Creating a Local Repository</title> + +<step><para> +Open the <guilabel>Create New Repository (cvs init)</guilabel> +dialog by choosing +<menuchoice><guimenu>Repository</guimenu> +<guimenuitem>Create...</guimenuitem></menuchoice>. +</para></step> + +<step><para> +Press the <guilabel>...</guilabel> button to select the folder where you want to +create the repository, or enter its location in the text box. For instance, if you +want to place the repository in the <filename>/home/user</filename> folder, and +to name it <filename>cvsroot</filename>, you should type +<filename>/home/user/cvsroot</filename> in the text box, or select the +<filename>/home/user</filename> folder using the file picker, and add +<filename>cvsroot</filename>. +</para></step> + +<step><para> +Confirm by pressing the <guibutton>OK</guibutton> +button. &cervisia; will create and initialize the new repository folder. +</para></step> + +<step><para> +Now you can import your current work to the repository, or simply create a +folder in the repository to start a new module from scratch. +</para></step> + +</procedure> + +</tip> + + +<para> +&cervisia; offers an integrated front-end to manage all your repository +locations, the <guilabel>Configure Access to Repositories</guilabel> dialog. +To display it, select the <menuchoice><guimenu>Repository</guimenu> +<guimenuitem>Repositories...</guimenuitem></menuchoice> menu item. +</para> + +<figure id="screenshot-repositories" float="1"> +<title>A screenshot of &cervisia;'s Configure Access to Repositories dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="repositories.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s Configure Access to +Repositories dialog</phrase></textobject> +</mediaobject> +</figure> + +<para> +There are several methods to access a CVS repository. It may be reached via +password authentication (:pserver:), secure shell (using :ext:), local +repository (:local:), &etc;. The format for the repository location is +(optional items appear between square brackets): +</para> + +<para> +<filename>[:method:][[user][:password]@]hostname[:[port]]/path/to/repository</filename> +</para> + +<para> +Not all these items (user, password, hostname, port) are always necessary +to access the repository. The required information depends on the access method +used, which can be categorized as follows: +</para> + +<variablelist> + +<varlistentry> +<term>Local</term> + +<listitem> +<para> +The local access method is the default method used by &CVS;. Therefore, it is +optional to add the :local: method to the repository location: you can enter +simply the path to the folder which stores the &CVS; +repository, and is accessible from your computer, like +<filename class="directory">/path/to/repository</filename> or to give a real +life example, <filename class="directory">/home/cvs</filename>.</para> + +<para> +It may physically be on a disk which is mounted via <acronym>NFS</acronym>, +but this is an irrelevant detail. If you created a local repository, the +location will be simple the path to it. +</para> +</listitem> +</varlistentry> + +<varlistentry id="rsh"> +<term>rsh</term> + +<listitem> +<para> +The repository location is something like +<filename>:ext:username@host.url.org:/path/to/repository</filename>. +</para> + +<para> +This method requires that you have a user account on the server machine (in +this example, <systemitem class="systemname">host.url.org</systemitem>) and +use a remote shell for communication. By default, &CVS; uses ↱ for this +purpose; however, ↱ has long considered to be insecure, and is widely +replaced by &ssh;. +</para> + +<para> +If you wish to use &ssh;, you must set the environment variable +$<envar>CVS_RSH</envar> to &ssh; when using the <command>cvs</command> +client. &cervisia; supports this easily. +</para> + +<!-- TODO: verify if the above still apply --> + +<para> +Note that &cervisia; cannot answer possible password requests from the +server machine. You must make sure that a remote login works without requiring +you to enter the password. With plain vanilla ↱, this can be achieved for +example by creating a <filename>.rhosts</filename> file in your home folder +with a list of trusted hosts (see the ↱ manpage). +</para> + +<para> +With &ssh;, it can be achieved by copying your public key located in the file +<filename>identity.pub</filename>, located in the +<filename>$<envar>HOME</envar>/.ssh/</filename> folder to the server. In this +case, the key must not be encrypted with a passphrase (see the &ssh; manpage and +the &CVS;/<acronym>SSH</acronym> <acronym>FAQ</acronym> on +SourceForge). If you are unsure about these issues, ask your system +administrator. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>pserver</term> + +<listitem> +<para> +The repository location looks like +<filename>:pserver:username@host.url.org:/path/to/repository</filename> +</para> + +<para> +This method accesses the server via a special protocol with a relatively weak +authentication (<literal>pserver</literal> stands for password +authentication). Before you can use such a server, you need a username and +password given by the &CVS; server administrator, and you have to login. Note +that your &CVS; password authentication username does not necessarily match the +system's username. Before accessing the &CVS; server, you will need to login. +</para> + +<para> +Open-source projects typically offer Anonymous CVS access to their +sources. This means you can easily grab the latest sources, modify, and create +patches (differences) against the repository without asking for a CVS account. +As a general rule, Anonymous CVS uses password authentication (:pserver:), and +is a read-only repository, not allowing you to upload your changes directly. +</para> + +</listitem> +</varlistentry> +</variablelist> + +<para> +Knowing the access method and location to the repository, you can add it +to &cervisia;'s repositories list: +</para> + +<procedure> +<title>Adding a New Repository</title> + +<step><para> +Open the <guilabel>Configure Access to Repositories</guilabel> dialog by +choosing the <menuchoice><guimenu>Repository</guimenu> +<guimenuitem>Repositories...</guimenuitem></menuchoice> menu item. +</para></step> + +<step><para> +Press the <guilabel>Add...</guilabel> button to open the +<guilabel>Add Repository</guilabel> dialog. +</para></step> + +<step><para> +Enter the repository location in the <guilabel>Repository:</guilabel> text box. +&cervisia; will automatically disable the areas of the dialog that are not +relevant to the access method you entered. +</para></step> + +<step><para> +If you are using the ext method to access the repository, enter the remote shell +you wish to use (⪚ &ssh;) in the <guilabel>Use remote shell (only for :ext: +repositories):</guilabel> text box. +</para></step> + +<step><para> +Press <guibutton>OK</guibutton>. You will see the repository you just entered +on the repositories list. +</para></step> + +<step><para> +If the access method to the repository you just entered is password +authentication (pserver), you will need to login before connecting the server. +Click the repository on the list to select it, and press the +<guilabel>Login...</guilabel> button. Enter your password in the upcoming dialog. +</para> +<para> +If you successfully enter your password, the <guilabel>Status</guilabel> +column entry of the pserver repository will change from +<guilabel>Not logged in</guilabel> to <guilabel>Logged in</guilabel>. +</para></step> + +<step><para> +Press <guibutton>OK</guibutton> to apply your modifications, or add another +location to the list. &cervisia; will store as many locations as you like. +</para></step> + +</procedure> + +</sect1> + + +<sect1 id="importing"> +<title>Importing a Module Into the Repository</title> + +<para> +In this section, we discuss how you can put a new project into the &CVS; +repository. If you just want to work with an existing project which is already +in a repository, you may skip this section. +</para> + +<para> +There are two ways to put a project into the &CVS;: +</para> + +<itemizedlist> + +<listitem><para> +Import the files and folders to a new <firstterm>module</firstterm>, using +&cervisia;'s import dialog. Modules are the top folders in the &CVS; repository +folder tree, and are used to separate and organize the different software +projects inside the repository. +</para></listitem> + +<listitem><para> +Create an empty module and add the new files and folders manually. You will have +more control, but it will probably take a little more time. +</para></listitem> + +</itemizedlist> + +<important> +<para> +Keep in mind that &CVS; was initially designed to handle +text files. Many features, like revision merging, creating differences in a +readable form, &etc; are only performed to text files. This does not mean you +cannot use CVS to keep binary files, it just means you have to +<emphasis>explicitly tell CVS if it is a text or binary file</emphasis>. If +you declare the wrong file type, you will experience problems with the &CVS; +functionality for these files, and they may get corrupted. +</para> +</important> + + +<para> +Importing a project (as a new module) has some advantages: you will import all +files and folders recursively, and the module will automatically be created +for you. This makes importing large existing projects to the repository +easier. However, there are some disadvantages: you cannot use &cervisia;'s import +dialog to add files to existing modules, and you can either import the files +as text or binary files. You can work around this limitation by creating a +folder with files of only one of the types, or by informing the patterns +of the files that should be ignored during the import process. +</para> + +<para> +For instance, suppose your project contains text files and some PNG images +(binary files) only. You can tell &CVS; to ignore all files with the pattern +<filename class="extension">*.png</filename> while importing the other files as +text, or you can move the images to a separate folder, and then import +the remaining files (as text files). Either way, you will have to +<link linkend="checkingout">checkout</link> the newly imported module to a +new working copy, copy the missing files and folders to it, +<link linkend="addingfiles">add</link> and +<link linkend="committingfiles">commit</link> them to the repository to complete +the import process. +</para> + +<para> +As an alternative, you can add the files and folders manually, creating an empty +module for them. To add an empty module to a repository, just create a new +folder in the &CVS; repository root folder. The name of this new folder will be +the name of the module. <link linkend="checkingout">Checkout</link> the new +empty module. Then copy the files and folders to the working copy, +<link linkend="addingfiles">add</link> and +<link linkend="committingfiles">commit</link> to upload them to the &CVS; +repository. +</para> + + +<figure id="screenshot-import" float="1"> +<title>A screenshot of &cervisia;'s import dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="import.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s import dialog</phrase></textobject> +</mediaobject> +</figure> + +<para> +In <xref linkend="screenshot-import"/> you can see the dialog which helps you +to <emphasis>import</emphasis> a project as a module. To access &cervisia;'s +import dialog, choose the <menuchoice><guimenu>Repository</guimenu> +<guimenuitem>Import...</guimenuitem></menuchoice> +menu item. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Repository:</guilabel> <xref linkend="co-repository" /></term> +<listitem><para> +Enter or select on the dropdown list the name of the &CVS; repository, also +known as $<envar>CVSROOT</envar>. You must have write access to it, and the +repository must be properly initialized. If the repository does not yet exist, +you can create one choosing the +<menuchoice> +<guimenu>Repository</guimenu> +<guimenuitem>Create...</guimenuitem> +</menuchoice> +menu item. +</para> +<para> +The drop down box shows a +list of the repositories you previously entered using the <guilabel>Configure +Access to Repositories</guilabel> dialog box. If the repository is remote, +make sure that authentication works. See <xref +linkend="accessing-repository"/> for more information. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Module:</guilabel> <xref linkend="co-module" /></term> +<listitem><para> +The name of the module under which the project will be stored. After +the import, the project can be checked out under this name. See +<xref linkend="checkingout"/> for more information. This is also the name of +the corresponding folder in the repository. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Working Folder:</guilabel></term> +<listitem><para> +The toplevel folder of the project you want to import. The import +starts from this folder and goes down recursively. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Vendor tag:</guilabel> <xref linkend="co-vendortag" /></term> +<listitem><para> +The vendor tag is historically used for tracking third-party sources. Just use +your user name if you have no better idea. It does not matter much what you +enter here. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Release tag:</guilabel> <xref linkend="co-releasetag" /></term> +<listitem><para> +This tag is also historically used for importing different versions of +third-party software. If you are not doing this, use the word +<literal>start</literal> or a string <literal>FOO_1_0</literal> where +<literal>FOO</literal> is the name of your project and <literal>1.0</literal> +is the version number of the imported release. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Ignore files:</guilabel></term> +<listitem><para> +If you fill out this field, an additional <option>-I <replaceable>file names</replaceable></option> +option is given go the <command>cvs import</command> command. This entry is +interpreted as a whitespace-separated list of file name patterns which are +ignored. In general, a cleaner and less error-prone way to control which files +go into the repository is to create a folder with only the files which you +want to import and start from that. Nevertheless, this entry may be useful if +the project contains files which are by default ignored by &CVS;, ⪚ files +with the name <filename>core</filename>. In such a case, simply enter the +character <literal>!</literal> in this field: this overrules &CVS;'s scheme of +ignored files, see <xref linkend="ignoredfiles"/>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Comment:</guilabel> <xref linkend="co-comment" /></term> +<listitem><para> +Use this field to record the comments you might have about the origin, use, +development, &etc; of the files you are importing. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Import as binaries</guilabel></term> +<listitem><para> +If you check this box, all files are imported in binary mode, i.e. an argument +<option>-kb</option> is given to <command>cvs import</command>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use file's modification as time of import</guilabel></term> +<listitem><para> +If you check this box, the time of import will be the file's modification time +instead of the import time. +</para></listitem> +</varlistentry> + +</variablelist> + + +<para>After you have filled out this form and confirmed by +pressing <guibutton>OK</guibutton>, the following &CVS; command is used:</para> + +<screen><command>cvs</command> -d <co id="co-repository"></co><replaceable>repository</replaceable> import -m "<co id="co-comment"></co>" <co id="co-module"></co><replaceable>module</replaceable> <co id="co-vendortag"></co><replaceable>vendortag</replaceable> <co id="co-releasetag"></co><replaceable>releasetag</replaceable></screen> + +</sect1> + + +<sect1 id="checkingout"> +<title>Checkout a Module From the Repository</title> +<para> +Now that you successfully defined your repository location, and imported the +initial files to the repository, it is time to retrieve the module from the +&CVS; repository, creating your working copy. +</para> + +<para> +You should also know the name of the <firstterm>branch</firstterm> or +<firstterm>tag</firstterm> you want to use. +</para> + +<para> +Branches of a module are parallel versions of this module. A good real-life +example of the use of this feature is the release of a software project. After a +major release, there are bugs in the code that should be fixed, but people want +to add new features to the application too. It is very hard to do both at the +same time because new features usually introduce new bugs, making it hard to +track down the old ones. To solve this dilemma, &CVS; lets you create a parallel +version, that we will call the "stable release branch", where you can +only add bugfixes, leaving the main branch (HEAD) open for adding new features. +</para> + +<para> +Tags are used to mark a version of a project. &CVS; stamps one +version of each file with the tag, so when you checkout or +update to a specific tag, you will get always the same file versions. +Therefore, in opposition to branches, tags are not dynamic: you cannot develop a +tag. Tags are useful to mark releases, big changes in the code, &etc;. +Using tags, you can easily return the project to a previous state, to reproduce and +track bugs, generate the release code again, &etc;. +</para> + +<figure id="screenshot-checkout" float="1"> +<title>A screenshot of &cervisia;'s checkout dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="checkout.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s checkout dialog</phrase></textobject> +</mediaobject> +</figure> + +<variablelist> + +<varlistentry> +<term><guilabel>Repository:</guilabel></term> +<listitem><para> +The name of the &CVS; repository, also known as +<filename><envar>$CVSROOT</envar></filename>. The drop-down box shows a +list of the repositories you previously entered using the <guilabel>Configure +Access to Repositories</guilabel> dialog box. If the repository is remote, +make sure that authentication works. See <xref +linkend="accessing-repository"/> for more information. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Module:</guilabel></term> +<listitem><para> +The name of the module to be checked out. If you are working with an existing +repository, you can probably get this name from the system administrator; +or, if it is an open-source repository, you can get the module names from the +project web pages. If you want to create a new module from scratch using a local +repository, just create a new folder in the local repository root folder. The +name of the folder will be the same as the name of the empty module. +</para> +<para> +Alternatively, if the repository has a +<filename><envar>$CVSROOT</envar>/modules</filename> file, you can retrieve a +list of available modules by pressing the <guibutton>Fetch list</guibutton> +button. +</para> +<para> +Note that it is possible to checkout any existing subfolder of the module, +without retrieving the rest of the module. Just enter the path to the subfolder +as well. For instance, if you want to get only the +<filename class="directory">doc/cervisia</filename> subfolder of the kdesdk +module, enter <filename class="directory">kdesdk/doc/cervisia</filename> in this +field. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Branch tag:</guilabel></term> +<listitem><para> +The name of the branch or tag you want to check out. If you leave this field +empty, &cervisia; will retrieve the main (HEAD) branch. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Working folder:</guilabel></term> +<listitem><para> +The folder under which the module should be checked out. Note that the +the working copy toplevel folder is named after the module you are retrieving, +unless you give it an alternative name in the <guilabel>Check out as:</guilabel> +field. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Check out as:</guilabel></term> +<listitem><para> +This results in the working copy files being checked out to an alternative +folder under the working folder rather than a folder named after the module. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Export only</guilabel></term> +<listitem><para> +If you check this box, the files will be exported rather than checked out. +Exporting obtains a copy of the source for the module without the CVS +administrative folders. For example, export may be used to prepare the +source code for a release. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + + +<sect1 id="mainscreen"> +<title>The Main Screen, Viewing File Status and Updating</title> +<para> +When you start &cervisia;, and open a working copy by choosing +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Open Sandbox...</guimenuitem> +</menuchoice>, +you can see two main areas in &cervisia;'s main window: the top one is a +hierarchical (tree) view of the current working copy; the bottom area is +used to display the &CVS; commands &cervisia; issues to perform its tasks, as +well as the output generated by these commands. +</para> + +<para> +By default, &cervisia; does not display the files contained by the sub-folders, +so you will have to click the folders you want to see. To display all files +of the working copy, select +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Unfold File Tree</guimenuitem> +</menuchoice>. +To close back all folders from the working copy, choose +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Fold File Tree</guimenuitem> +</menuchoice>. +</para> + +<para> +According to the settings in your +<filename>.cvsignore</filename> files, the files you usually do not want to +include into the repository - such as object files - are not shown in the tree +view. For each file, you see its corresponding status. In the default setting, +after opening the sandbox, this is "Unknown" because &cervisia; delays the +fetching of information until you select the files and folders whose status you +want to update or view and choose +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Update</guimenuitem> +</menuchoice> +or +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Status</guimenuitem> +</menuchoice>. With this approach, you have a minimal +amount of functionality available even if you do not have a permanent +connection to the &CVS; server. +</para> + +<figure id="screenshot-mainview" float="1"> +<title>A screenshot of &cervisia;'s main view</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="mainview.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s main view</phrase></textobject> +</mediaobject> +</figure> + +<para> +The commands in the File menu usually act only on the files which you have +marked. You may also mark folders. Now choose +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Status</guimenuitem> +</menuchoice> or press <keycap>F5</keycap>. &cervisia; issues a +</para> + +<para> +<screen><command>cvs update -n <replaceable>file names</replaceable></command></screen> +</para> + +<para> +command to get status information for the marked files. Note that &cervisia; +goes recursively into subfolders only if you have the according option +in the <guimenu>Settings</guimenu> menu set. According to the respective +file's status, you now see an entry in the <guilabel>Status</guilabel> column: +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Locally Modified</guilabel></term> +<listitem><para> +This means you have modified the file compared to the +version in the repository. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Locally Added</guilabel></term> +<listitem><para> +This means the file does not exist in the repository, but in +your working copy and you have scheduled it for addition. The actual +insertion into the repository only happens after a commit. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Locally Removed</guilabel></term> +<listitem><para> +This means you have scheduled the file for removal, but it +still exists in the repository. The actual removal happens only after a +commit. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Needs Update</guilabel></term> +<listitem><para> +This is shown if a newer version of the file exists in the +repository, e.g. because someone committed a modification. Normally, you want +to update this file so you have an up-to-date version in your folder. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Needs Patch</guilabel></term> +<listitem><para> +This is essentially the same as before; the difference is +that in case of an update, the &CVS; server transfers only a patch +instead of the whole file to you. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Needs Merge</guilabel></term> +<listitem><para> +Indicates that a merge of the revision of this file in your +working copy with the version in the repository is necessary. This +typically happens if you have made modifications to the file while +someone else has committed his modifications. If you choose to update, the +modifications in the repository are merged into your file. In case of a +conflict (i.e. if someone else has changed some of the same lines like you) +the new status is then "Conflict". +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Up to Date</guilabel></term> +<listitem><para> +Indicates that the file is identical with the version in the +repository. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Conflict</guilabel></term> +<listitem><para> +This is shown if this file still has conflict markers in it. Maybe +you have previously updated the file and not resolved the conflicts. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Not In CVS</guilabel></term> +<listitem><para> +Indicates that the file is not registered in the &CVS; +repository. If you want it to available for others, you should add it to the +repository. If not, you may consider adding it to your +<filename>.cvsignore</filename> file. +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +Now that you have got an overview of the current status of the CVS, you may +want to do an update. Mark some files (or the root of the folder tree which +is equivalent to marking all files in this folder). Now choose +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Update</guimenuitem> +</menuchoice> (Of course, you could have chosen this at the beginning of +the session). For some +of the files the status may change now. Typically, files which had "Needs +Patch" or "Needs Update" are updated. So the following new items are possible +in the status column: +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Updated</guilabel></term> +<listitem><para> +Shown if the file was updated from the repository. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Patched</guilabel></term> +<listitem><para> +Indicates that the &CVS; server has sent a patch for this file and +the patch has been successfully applied. If the patch was not successful +because there was a conflict between your modifications and those someone else +committed to the repository, the status is now <guilabel>Conflict</guilabel>. +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +You may have noticed that according to the status of the file, its row has a +different color. The colors are chosen to somehow reflect the priority of the +status. For example, a file with a conflict is marked red to show you that you +have to resolve a conflict before you can continue working with the file. If +your folder contains a high number of files, you may nevertheless lose the +overview. To get more concise information about which files have an unusual +status, simply click on the header of the <guilabel>Status</guilabel> +column. The file list is then sorted by priority, so you have all important +information at the top of the list. To get back to the alphabetically sorted +view, click on the header of the <guilabel>File name</guilabel> column. +</para> + +</sect1> + +</chapter> + + +<chapter id="workingwithfiles"> +<title>Working With Files</title> + +<para> +All commonly used &CVS; functionality is directly available in &cervisia;'s +main view. Commands usually act on several files at once, namely all which +currently selected. If the selection includes folders, its interpretation +depends on the settings made under the <guimenu>Settings</guimenu> menu. For +example, if <menuchoice><guimenu>Settings</guimenu><guimenuitem>Commit and +Remove Recursively</guimenuitem></menuchoice> is checked and you choose +<menuchoice><guimenu>File</guimenu><guimenuitem>Commit...</guimenuitem></menuchoice> +while a folder is selected, then all files in the tree under that folder +are committed. Otherwise, only the regular files in the folder itself are +affected. +</para> + +<figure id="screenshot-popup" float="1"> +<title>A screenshot of &cervisia;'s context menu</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="popup.png"/></imageobject> +</mediaobject> +</figure> + +<para> +The most used actions are also available by right clicking the files in the tree +view, through the context menu. <xref linkend="screenshot-popup" /> shows +&cervisia;'s main window pop-up menu. +</para> + +<para> +You can simply edit a file by double-clicking on it or selecting it and pressing +&Enter;. This starts the default application that handles that +file type (the default application for each file type is a KDE wide setting). If +the default application is not the one you want to use, you can right click the +file and choose the +<menuchoice> +<guisubmenu>Edit With</guisubmenu> +</menuchoice> +submenu, and select one of the other applications that handle that file type. +</para> + +<sect1 id="addingfiles"> +<title>Adding Files</title> + +<para> +Adding files to a project requires two steps: first, the files must be +registered with &CVS;, or in other words, +<emphasis>added to the repository</emphasis>. This is necessary, but not +sufficient. In order to actually put the files into the repository, you must +<emphasis>commit</emphasis> them. This procedure has an important advantage: +you can commit the files together with modifications to other parts of the +project. When doing this, one can easily see (⪚ in commit emails) that all +these changes are part of a whole. +</para> + +<para> +To this end, mark all files to be added in &cervisia;'s +main view. Then, choose <menuchoice><guimenu>File</guimenu><guimenuitem>Add to +Repository...</guimenuitem></menuchoice>, or right click the marked files and +choose <guimenuitem>Add to Repository...</guimenuitem>. The +<guilabel>CVS Add</guilabel> dialog will appear, listing the files you marked, and +asks for confirmation. Press <guibutton>OK</guibutton>. +</para> + +<para>&cervisia; issues a command</para> + +<para> +<screen><command>cvs add <replaceable>file names</replaceable></command></screen> +</para> + +<para> +If the operation was successful, the status column should have "Added to +repository" for the added files. +</para> + +<warning><para> +&CVS; is not designed to provide meaningful revision control for binary +files. For example, merging binary files normally does not make +sense. Furthermore, by default &CVS; performs keyword expansion (⪚ on the +string <literal>$Revision: 1.6 $</literal>) when a file is committed. In binary +files, such replacements may corrupt the file and make it completely +unusable. +</para></warning> + +<para> +In order to switch the above behavior off, you should commit binary files +(or other files, like Postscript or PNG images) by choosing +<menuchoice><guimenu>File</guimenu><guimenuitem>Add Binary...</guimenuitem></menuchoice>. +The <guilabel>CVS Add</guilabel> dialog will appear, listing the binary files +you marked, and asks for confirmation. Press <guibutton>OK</guibutton>. +</para> + +<para> +&cervisia; issues a command +</para> + +<para> +<screen><command>cvs add -kb <replaceable>file names</replaceable></command></screen> +</para> + +</sect1> + + +<sect1 id="removingfiles"> +<title>Removing Files</title> + +<para> +Like adding files, removing files is done in two steps: First, the files have +to be registered as removed by choosing +<menuchoice><guimenu>File</guimenu><guimenuitem>Remove From +Repository...</guimenuitem></menuchoice> or right clicking the marked files and +choosing <guimenuitem>Remove From Repository...</guimenuitem> from the context +menu. The <guilabel>CVS Remove</guilabel> dialog will appear, listing the files +you marked, and asking for confirmation. Press <guibutton>OK</guibutton>. +&cervisia; issues the command +</para> +<para> +<screen><command>cvs remove -f <replaceable>file names</replaceable></command></screen> +</para> + +<para> +After that, this modification to the sandbox has to be committed, possibly +together with other modifications to the project. +</para> + +<note><para> +The above command only works if the file is up-to-date. Otherwise, you get an +error message. This behavior is sensible: If you have modified the file +compared to the version in the repository, or if someone else has made any +modifications, you will first want to check if you really want to discard +them. +</para></note> + +</sect1> + + +<sect1 id="addingremovingdirs"> +<title>Adding and Removing Folders</title> + +<para> +Folders are handled fundamentally different from ordinary files by +&CVS;. They are not under revision control, i.e. you cannot tell which +folders existed in the project at a certain time. Furthermore, folders +can never be explicitly removed (except by removing them directly in the +repository). +</para> + +<para> +As a substitute, &CVS; follows the convention that a folder is "non-existent" +in a version of the project if it is empty. This convention can be +enforced by using the option <option>-P</option> to <command>cvs +update</command> and <command>cvs checkout</command>. This option can be set +in the menu <menuchoice><guimenu>Settings</guimenu><guimenuitem>Prune Empty +Folders on Update</guimenuitem></menuchoice>. +</para> + +<para> +A folder can be added to the repository choosing +<menuchoice><guimenu>File</guimenu><guimenuitem>Add to +Repository...</guimenuitem></menuchoice> or right clicking the marked folder and +choosing <guimenuitem>Add to Repository...</guimenuitem> from the context menu. +Note that in contrast to adding files, adding folders does not require a commit +afterwards. &cervisia; issues the command +</para> + + +<para> +<screen><command>cvs add <replaceable>dirname</replaceable></command></screen> +</para> + +</sect1> + + +<sect1 id="committingfiles"> +<title>Committing Files</title> + +<para> +When you have made a certain number of changes to your working copy, and you +want other developers to have access to them, you <emphasis>commit</emphasis> +them. With a commit, you place your versions of the modified files as new +revisions into the repository. A subsequent update by another developer will +bring your modifications into their working copy. +</para> + +<para> +In order to commit a couple of files, select them in &cervisia;'s main view and +choose +<menuchoice><guimenu>File</guimenu><guimenuitem>Commit...</guimenuitem></menuchoice> +or right click the marked files and choose +<guimenuitem>Commit...</guimenuitem> from the context menu. +</para> + +<figure id="screenshot-commit" float="1"> +<title>A screenshot of &cervisia;'s commit dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="commit.png"/></imageobject> +</mediaobject> +</figure> + +<para> +You get a dialog that shows you a list of the selected files on the top section +and a log message for your changes below. &cervisia; helps you in several ways +to find a meaningful log message: first, in the file list you can double-click +a file or press <keycap>Return</keycap> in order to see the changes you have +made to the file. Second, it gives you a list of log messages you have +previously used in a combo box. Third, this dialog is integrated with +&cervisia;'s changelog editor described below. When you have finished the +dialog, the command +</para> + +<para> +<screen><command>cvs commit -m <replaceable>message</replaceable> <replaceable>file names</replaceable></command></screen> +</para> + +<para> +is used. +</para> + + +<note><para> +A common error you may encounter when committing is <errorname>Up-to-date check +failed</errorname>. This indicates that someone has committed changes to the +repository since you last updated; or, more technically, that your +<literal>BASE</literal> revision is not the newest on its branch. In such a +case, &CVS; refuses to merge your modifications into the repository. The +solution is to update, resolve any conflicts and commit again. Of course, if +you are working on a software project, it is normally good style to check if +the program still works after you have updated - after all, there could be bad +interactions between your modifications and the other modifications which +break the code. +</para></note> + +<note> +<para> +Another popular mistake results in the error message <errorname>Sticky tag 'X' +for file 'X' is not a branch</errorname>. This happens if you try to commit a +file which you have previously brought to a certain revision or tag with the command +</para> +<para> +<screen><prompt>%</prompt><userinput>cvs update -r X</userinput></screen> +</para> +<para> +(which is ⪚ used by the menu item +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Update to +Tag/Date...</guimenuitem></menuchoice>). In such a case, the tag on the file +gets sticky, i.e. further updates do not bring you to the newest revision on +the branch. If you want to commit further revisions to the branch, you have to +update to the branch tag before you do further commits. +</para> +</note> + +<para> +With &cervisia;, it is quite easy to maintain a ChangeLog file that is +compliant with the format laid out in the GNU coding guidelines. To use it, +choose <menuchoice><guimenu>File</guimenu><guimenuitem>Insert ChangeLog +Entry...</guimenuitem></menuchoice>. If a file with the name +<filename>ChangeLog</filename> exists in the toplevel folder of your +sandbox, this file will be loaded and you have the possibility to edit it. To +this end, at the top of the file, an entry with the current date and your user +name (which can be configured as described in <xref +linkend="customize-general"/>) is inserted. When you finish the dialog this +dialog by clicking <guibutton>OK</guibutton>, the next commit dialog you open +will have the log message set to the message you last entered in the ChangeLog. +</para> + +</sect1> + + +<sect1 id="resolvingconflicts"> +<title>Resolving Conflicts</title> + +<para> +Conflicts may occur whenever you have made changes to a file which was also +modified by another developer. The conflict is detected by &CVS; when you +update the modified file; &CVS; then tries to merge the modifications committed +by the other developer into your working copy. The merge fails if both your +and his modifications are in overlapping parts of the file, and the &CVS; +server issues an error message. +</para> + +<para> +In &cervisia;'s main view, files with conflicts are indicated with "Conflict" +in the status column and with a red color. It is your job now to resolve these +conflicts before you commit the file. &CVS; will refuse to commit any files with +conflicts until they have been edited. From the main view, you can of +course resolve conflicts the traditional way: just double-click the file in +question and edit it with your favorite editor.</para> + +<para> +&CVS; marks the conflicting changes by placing marks in the middle +of the files, in the following manner:</para> + +<screen> +<<<<<<< +Changes in your working copy +======= +Changes in the repository +>>>>>>> revision_number +</screen> + +<para>You should replace this whole block with the new merged version. Of +course, you have a great amount of freedom when resolving a +set of conflicts: for each conflict you can decide to take one of the two +alternative versions. You can also decide that both approaches are broken +and rewrite a whole routine or the complete file from scratch. +</para> + +<para> +Fortunately, &cervisia; offers a nicer interface for handling these conflicts. +This does not mean that you will never need to manually edit the files, but +at least can eliminate the need to do so for the trivial conflict resolution. +To use &cervisia;'s <guilabel>CVS Resolve</guilabel> dialog choose +<menuchoice><guimenu>File</guimenu><guimenuitem>Resolve...</guimenuitem></menuchoice> +or right click the marked file and choose +<guimenuitem>Resolve...</guimenuitem> from the context menu. +</para> + +<figure id="screenshot-resolve" float="1"> +<title>A screenshot of &cervisia;'s resolve dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="resolve.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s resolve dialog</phrase></textobject> +</mediaobject> +</figure> + +<para> +On the top of the dialog, you see <guilabel>Your version (A)</guilabel> of the +file on the left hand side and the version in the repository, <guilabel>Other +version (B)</guilabel>, on the right hand side. The differences +between them are marked in red color. Below these two versions, you can see +the <guilabel>Merged version</guilabel>. The merged version reflects what that +section will be in your working copy if you press the <guibutton>Save</guibutton> +button. +</para> + +<para> +You can go back and forward between the conflicting sections by pressing +<guibutton><<</guibutton> and <guibutton>>></guibutton>. In the +lower middle of the dialog you can see which section is currently marked. For +example, <literal>2 of 3</literal> means that you are currently at the second +differing section of 3 total. +</para> + +<para> +Now can can decide section by section which version you want to have in the +merged file. By pressing <guibutton>A</guibutton>, you take over the version you +edited. By pressing <guibutton>B</guibutton>, you take over the version from the +repository. By pressing <guibutton>A+B</guibutton>, both versions will be added, +and your version will come first. <guibutton>B+A</guibutton> yields the same +result, but the order will be different: first the repository version, then +yours. +</para> + +<para> +If you are not happy with any of these versions, press +<guibutton>Edit</guibutton> to open a simple text editor where you can +edit the section. When you are finished editing, press <guibutton>OK</guibutton> +to return to the <guilabel>CVS Resolve</guilabel> dialog and resume solving +conflicts. You will see the section you just edited in the +<guilabel>Merged version</guilabel>, with your modifications. +</para> + +<para> +To save your modifications, overwriting the working copy version, press +<guibutton>Save</guibutton>. Note that this will save the choices not only the +section you are currently viewing, but all sections in the file. If you want to +save it to another file, press <guibutton>Save As...</guibutton>. +Press <guibutton>Close</guibutton> to exit the dialog. If you close the dialog +without saving, the changes you made will be lost. +</para> + +</sect1> + +</chapter> + + +<chapter id="obtaininginformation"> +<title>Obtaining Information About Files and Creating Patches</title> + +<sect1 id="diff"> +<title>Watching Differences Between Revisions</title> + +<para> +There are several places in &cervisia; where you can ask for a window showing +the differences between revisions of a file: +</para> + +<itemizedlist> + +<listitem><para> +In the main view, you can choose +<menuchoice><guimenu>View</guimenu><guimenuitem>Difference to +Repository (BASE)...</guimenuitem></menuchoice>. This is based on the command +<command>cvs diff</command> and shows you the differences between the version +in your sandbox and the version to which you last updated (also known as +<literal>BASE</literal>). This is in particular useful just before you commit +a file, so you can find an appropriate log message. +</para></listitem> + +<listitem><para> +You can view the differences between the version in your sandbox and the version +in the main development branch (also called <literal>HEAD</literal>) by choosing +<menuchoice><guimenu>View</guimenu> +<guimenuitem>Difference to Repository (HEAD)...</guimenuitem></menuchoice>. +</para></listitem> + +<listitem><para> +You can view the differences between the last two revisions of the selected file +choosing <menuchoice><guimenu>View</guimenu> +<guimenuitem>Last Change...</guimenuitem></menuchoice>. +</para></listitem> + +<listitem><para> +You can access the <guimenuitem>Difference to Repository (BASE)...</guimenuitem>, +<guimenuitem>Difference to Repository (HEAD)...</guimenuitem> and +<guimenuitem>Last Change...</guimenuitem> menu items from the main view context +menu, by right-clicking the file you want to view. +</para></listitem> + +<listitem><para> +In the dialog that is shown when a you commit a set of files, you can request +a difference window by selecting a file name in the selection list, either by +double-clicking it or by pressing <keycap>Return</keycap>. This is quite +similar to using <menuchoice><guimenu>View</guimenu><guimenuitem>Difference +to Repository (BASE)...</guimenuitem></menuchoice> with the respective file in the +main view. +</para></listitem> + +<listitem><para> +In the Browse Logs dialog, you can mark two revisions of a file and request a +dialog showing the differences between them (see <xref linkend="browsinglogs"/>). +</para></listitem> + +</itemizedlist> + +<para> +As you may have expected, &cervisia; does not just dump the output of the +<command>diff</command> command into your terminal, but shows you a graphical +view as seen in <xref linkend="screenshot-log"/>. +</para> + +<figure id="screenshot-log" float="1"> +<title>A screenshot of &cervisia;'s diff dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="diff.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s diff dialog</phrase></textobject> +</mediaobject> +</figure> + +<para> +The text in the dialog is an improved variant of the text given by the diff +command with the <option>-u</option> option. You can see the differing +versions in two windows, with lines arranged such that you can do a +side-by-side comparison. That means, where text has been added or deleted, +the respective window shows empty lines with the marker +<literal>+++++</literal> at the left hand side. Elsewhere, you can see the +running number of each line in the left column. +</para> + +<para> +In the second column in the right window, you can see which kind of change has +been made. Possible types are <literal>Add</literal>, +<literal>Delete</literal> and <literal>Change</literal>. The respective lines +are marked in blue, green and red color. In the middle of the dialog a +compressed image of the color markers is shown. In this way, you can get a +quick overview of the overall changes to the file. You can also use the +position of the colored regions in the compressed image as an orientation when +you using the scroll bars. +</para> + +<para> +Normally, the scrollbars at the left and the right window are synchronized, +i.e. if you scroll on the left hand side, the right hand side is scrolled by +the same amount. You can change this by checking the box +<guibutton>Synchronize scroll bars</guibutton>. +</para> + +<para> +For information about how to customize the diff dialog, see <xref linkend="customize-diff"/>. +</para> + +</sect1> + +<sect1 id="creatingpatches"> +<title>Creating Patches</title> + +<para> +Sometimes you want to offer your modifications for review, before committing them, +or you do not have write access to the repository (therefore you cannot +commit). &CVS; offers standard formats to share the modifications in +your working copy, so other people can review your changes, test them in their +working copy and apply them to the &CVS; repository. A file containing these +differences is called a <firstterm>patch</firstterm>, and is generated by the +<command>cvs diff</command> command, in the same way as the differences in +<xref linkend="diff"/>. Sharing patches instead of sets of files requires less +bandwidth, and patches are easier to handle, as you can send only one patch +file containing all the differences from many source files. +</para> + +<para> +&cervisia; gives you access to this feature by choosing +<menuchoice><guimenu>Advanced</guimenu> +<guimenuitem>Create Patch Against Repository...</guimenuitem></menuchoice>. +</para> + +<important><para> +The <guimenuitem>Create Patch Against Repository...</guimenuitem> action +creates a patch with all modifications in all files in your working copy +(sandbox) against the <literal>BASE</literal> repository. Therefore, the +selection of files in the main view does not affect the patch that will be +generated. +</para></important> + +<para> +Another possibility is to select one file in the main view and choose +<guimenuitem>Browse Log...</guimenuitem> from the <guimenu>View</guimenu> menu +or right click the marked file and choose +<guimenuitem>Browse Log...</guimenuitem> from the context menu, in order to open +the <link linkend="browsinglogs">Browse log dialog</link>. Now, select the +version you want to create a patch against, as revision "A" and press +the button <guilabel>Create Patch...</guilabel>. This will generate a patch with +the differences between the <emphasis>marked file</emphasis> in your working +copy and the version selected as revision "A". +</para> + +<para> +Before generating the patch, &cervisia; displays a dialog allowing you to +configure the output format. +</para> + +<figure id="screenshot-patch" float="1"> +<title>A screenshot of &cervisia;'s patch dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="patch.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s patch dialog</phrase></textobject> +</mediaobject> +</figure> + +<variablelist> + +<varlistentry> +<term><guilabel>Output Format</guilabel></term> +<listitem><para> +There are three output formats available: +</para> +<para> +<guilabel>Normal</guilabel>: a format that can be used to cause the ed editor +to automatically make another copy of the old file match the new file. In +the normal output format, the characters < and > mark the changes, and +there is no context information. +</para> +<para> +<guilabel>Unified</guilabel>: the most used format for +exchanging patches. The unified format uses context lines in addition to line +numbers to record the differences. This makes the process of +applying patches more robust. This format displays the +differences in a compact and readable form, with a header for each file +involved, and separate sections (chunks) for each difference. The context lines +available for each difference make reading the modifications easier. In +the unified output format, the characters + and - mark the changes. +</para> +<para> +<guilabel>Context</guilabel>, which presents the same information as the unified +format, but in a less compact way. In the context output format, the character ! +marks the changes. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Number of context lines:</guilabel></term> +<listitem><para> +Set here the number of context lines for the unified or context output formats. +This option is not available for the normal output format, as in this format +no context information is recorded. More context information makes reading the +raw output easier, and applying the patch more precise, but increases the patch +size. It is recommended to use at least two context lines for proper patch +operation. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Ignore Options</guilabel></term> +<listitem><para> +Check here the changes that should not be considered as differences when +generating the patch. +</para></listitem> +</varlistentry> + +</variablelist> + + +<para> +After setting the output format, &cervisia; generates the patch and displays the +<guilabel>Save As</guilabel> dialog. Enter in this dialog the file name +and location of the patch file. +</para> + + +</sect1> + +<sect1 id="annotate"> +<title>Watching an Annotated View of a File</title> + +<para> +With the command <command>cvs annotate</command>, &CVS; offers the possibility +to see - for each line in a file - who has modified a line the most recently. +This view may be helpful in order to find out who has introduced a change in +the behavior of a program or who should be asked about some change or bug in +the code. +</para> + +<para> +&cervisia; gives you access to this feature, but it further enriches the +information in an interactive way. You obtain an annotate view by choosing +<menuchoice><guimenu>View</guimenu><guimenuitem>Annotate...</guimenuitem></menuchoice>. +Another possibility is to press the button <guilabel>Annotate</guilabel> in +the <link linkend="browsinglogs">Browse log dialog</link>, in which you can +select which version of the file you want to display. +In <xref linkend="screenshot-annotate"/> you can see a screenshot of the +dialog. +</para> + +<figure id="screenshot-annotate" float="1"> +<title>A screenshot of &cervisia;'s annotate dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="annotate.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s annotate dialog</phrase></textobject> +</mediaobject> +</figure> + +<para> +In the annotate dialog, you see in a window the latest version of the selected +file (or the revision "A" version, in case you launched the annotate +dialog from the the <link linkend="browsinglogs">Browse log dialog</link>). In +the columns before the text, you get some information related to the +latest change in each line. In the first column the line number is +displayed. In the second column you see the name of the author and +revision number. Finally, in the third column you see the actual content of that +line. +</para> + +<para> +Consequently, when a certain line appears strange to you or you assume a bug +there, you can immediately see who is responsible for that line. But not only +that, you can also find out <emphasis>why</emphasis> that line was +changed. To this end, move the mouse cursor over the respective revision +number. Then a tooltip appears that shows the log message and the date of the +change. +</para> + +</sect1> + + +<sect1 id="browsinglogs"> +<title>Browsing &CVS; Logs</title> + +<para> +When you mark one file in the main view and choose <guimenuitem>Browse +Log...</guimenuitem> from the <guimenu>View</guimenu> menu +or right click the marked file and choose +<guimenuitem>Browse Log...</guimenuitem> from the context menu, the +<guilabel>CVS Log</guilabel> dialog is shown (if you mark more than one, nothing +happens, as &cervisia; can only generate and parse the log for one file at a +time). This dialog offers functionality that is beyond viewing the file's +history. Using it as a version browser you can: +</para> + +<itemizedlist> + +<listitem><para> +View the revision, author, date, branch, commit message, and tags for each +version of the marked file. +</para></listitem> + +<listitem><para> +View a graphical tree representation showing the branching and tagging of the +marked file. +</para></listitem> + +<listitem><para> +View any version of the marked file (with the default application). +</para></listitem> + +<listitem><para> +Watch an annotated view of any version of the marked file +</para></listitem> + +<listitem><para> +View the differences between any pair of versions of the marked file, +including pairs with the current working copy version of the marked file. +</para></listitem> + +<listitem><para> +Create patches containing the differences between any pair of versions of the marked +file, including pairs with the current working copy version of the marked file. +</para></listitem> + +</itemizedlist> + +<figure float="1"> +<title>A screenshot of &cervisia;'s browse logs dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="logtree.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s browse logs dialog</phrase></textobject> +</mediaobject> +</figure> + +<para> +You can choose to see the history as provided by the <command>cvs +log</command> command (<guilabel>CVS Output</guilabel>), as a +<guilabel>Tree</guilabel>, or in <guilabel>List</guilabel> form. What you prefer +is of course a matter of taste and it depends on what information you are +interested in. The tree is an intuitive representation of what has been done +on different branches by which authors. As tooltips, you can see the corresponding +log messages. The list is by its nature linear and, therefore, does not give an +immediate view of branches; on the other hand, it concentrates more otherwise +relevant information on less screen estate, namely the time of each change of +the file and the first part of the log message. The CVS output information is +complete, but long, and difficult to read. To alleviate these problems, you +have the ability to search the text of the CVS output, by pressing the +<guibutton>Find...</guibutton> button. +</para> + +<para> +To obtain more information about a certain revision, you can click on it +either in the list or the tree view. The fields in the middle of the dialog +are then filled with the complete information provided by <command>cvs +log</command>. You can mark two revisions, called "A" and "B", which are +relevant if you make use of further features provided by the buttons. +Revision "A" can be chosen with the left mouse button, revision "B" +with the middle one. In the list view, you can also +navigate with with your cursor keys. In order to mark revisions "A" and "B", +use the keybindings <keycombo><keycap>Ctrl</keycap><keycap>A</keycap></keycombo>, +<keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo>, respectively. +Using the <guilabel>CVS Output</guilabel> view, you can click on the +<guilabel>Select for revision A</guilabel> and <guilabel>Select for +revision B</guilabel> to mark the revisions. +</para> + +<para> +If you press the <guibutton>Annotate</guibutton> button, you get a dialog +showing the text of file belonging to the revision marked as "A". +Every line is prefixed with the information about who edited this last time, +and at which revision this happened. You can get more information about viewing +annotated versions in <xref linkend="annotate" />. +</para> + +<para> +If you press the <guibutton>Diff</guibutton> button, a <command>cvs diff</command> +call is issued and you get a dialog in which all the modifications between the +two marked revisions are shown. If you mark revision "A", but not +revision "B", &cervisia; will generate the modifications between +the file version marked as revision "A" and the working copy version +of the file. This allows you to view the differences between your version of the +file and any version available in &CVS;. To make it easy to see the changes, +different colors are used to mark lines which have been added, removed or simply +changed. You can get more information about viewing differences in +<xref linkend="diff" />. +</para> + +<para> +If you press the <guibutton>Create Patch...</guibutton> button, you get a dialog +in which you can set the format options for generating a file containing all the +modifications between the two marked revisions which are shown. If you mark +revision "A", but not revision "B", &cervisia; will generate +the modifications between the file version marked as revision "A" and +the working copy version of the file. This allows you to generate a patch, or +difference file, between your version of the file and any version available in +&CVS;. After configuring the format of the patch in the dialog, and pressing +<guibutton>OK</guibutton>, a <command>cvs diff</command> command is issued to +generate the difference file. A <guilabel>Save As</guilabel> dialog will pop up. +Enter the file name and location of the patch file &cervisia; generated, in order +to save it. You can get more information about creating patches, and the patch +format options in <xref linkend="creatingpatches" />. +</para> + +<para> +If you press the <guibutton>View</guibutton> button, &cervisia; will retrieve +the revision marked as "A" and display it using the default +application for its file type. +</para> + +<para> +Press the <guibutton>Close</guibutton> button to leave the dialog and return to +the main view. +</para> + + +<para> +To generate the log that is the base for the <guilabel>CVS Log</guilabel> +dialog, &cervisia; issues the following command: +</para> + + +<para> +<screen><command>cvs log <replaceable>file name</replaceable></command></screen> +</para> + +</sect1> + +<sect1 id="browsinghistory"> +<title>Browsing the History</title> + +<para> +If the used repository has logging enabled, &cervisia; can present you a +history of certain events like checkouts, commits, rtags, updates and +releases. Choose <guimenuitem>History</guimenuitem> from the +<guimenu>View</guimenu> menu, and &cervisia; will issue the command +</para> + +<para> +<screen><command>cvs history -e -a</command></screen> +</para> + +<note><para> +This fetches the complete logging file from the server, i.e. a list of +the events for all users and all modules. This can be a huge amount of data. +</para></note> + +<para> +Now you can see the list of events, sorted by date. In the second column, the +type of the event is shown: +</para> + +<itemizedlist> + +<listitem><para> +Checkout - The user who is displayed in the 'Author' column +has checked out a module +</para></listitem> + +<listitem><para> +Tag - A user has used the command <command>cvs rtag</command>. Note that the +usage of <command>cvs tag</command> (as done by &cervisia;'s +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Tag/Branch...</guimenuitem></menuchoice> +command) is not recorded in the history database. This has historical reasons +(see the &CVS; <acronym>FAQ</acronym>). +</para></listitem> + +<listitem><para> +Release - A user has released a module. Actually, this command is rarely used +and not of much value. +</para></listitem> + +<listitem><para> +Update, Deleted - A user has made an update on a file which was deleted in the +repository. As a consequence, the file was deleted in his working copy. +</para></listitem> + +<listitem><para> +Update, Copied - A user has made an update on a file. A new version was copied +into working copy. +</para></listitem> + +<listitem><para> +Update, Merged - A user has made an update on a file. The modifications in the +repository version on the file were merged into his working copy. +</para></listitem> + +<listitem><para> +Update, Conflict - A user has made an update on a file, and a conflict with +his own modifications was detected. +</para></listitem> + +<listitem><para> +Commit, Modified - A user committed a modified file. +</para></listitem> + +<listitem><para> +Commit, Added - A user added a file and committed it. +</para></listitem> + +<listitem><para> +Commit, Removed - A user removed a file and committed it. +</para></listitem> + +</itemizedlist> + +<figure id="screenshot-history" float="1"> +<title>A screenshot of &cervisia;'s history dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="history.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s history dialog</phrase></textobject> +</mediaobject> +</figure> + +<para> +You can sort the list by other criteria simply by clicking on the respective +column header. In order to sort out the history entries you are interested in, +there are various filter options activated by check boxes: +</para> + +<itemizedlist> +<listitem><para>Show commit events - shows commits</para></listitem> +<listitem><para>Show checkout events - shows checkouts</para></listitem> +<listitem><para>Show tag events - shows taggings</para></listitem> +<listitem><para>Show other events - shows events not included in the above</para></listitem> +<listitem><para>Only user - shows only events caused by a certain user</para></listitem> +<listitem><para>Only file names matching - filters file names by a regular expression</para></listitem> +<listitem><para>Only dirnames matching - filters folder names by a regular expression</para></listitem> +</itemizedlist> + +<para> +Special characters recognized by the regular expression matcher are: +</para> + +<itemizedlist> + +<listitem><para> +<literal>x*</literal> matches any number of occurrences of the character +<literal>x</literal>. +</para></listitem> + +<listitem><para> +<literal>x+</literal> matches one or more of occurrences of the character +<literal>x</literal>. +</para></listitem> + +<listitem><para> +<literal>x?</literal> matches zero or one occurrences of the character +<literal>x</literal>. +</para></listitem> + +<listitem><para> +<literal>^</literal> matches the start of the string. +</para></listitem> + +<listitem><para> +<literal>$</literal> matches the end of the string. +</para></listitem> + +<listitem><para> +<literal>[a-cx-z]</literal> matches a set of characters, +⪚ here the set consisting of a,b,c,x,y,z. +</para></listitem> + +</itemizedlist> + +</sect1> + + +</chapter> + +<chapter id="advancedusage"> +<title>Advanced Usage</title> + +<sect1 id="updatingto"> +<title>Updating to Tag, Branch or Date</title> + +<para> +Branches of a module are parallel versions of this module. A good real life +example of the use of this feature is the release of a software project. After a +major release, there are bugs in the code that should be fixed, but people want +to add new features to the application too. It is very hard to do both at the +same time because new features usually introduce new bugs, making it hard to +track down the old ones. To solve this dilemma, &CVS; lets you create a parallel +version, that we will call the "stable release branch", where you can +only add bugfixes, leaving the main branch (HEAD) open for adding new features. +</para> + +<para> +Tags are used to mark a version of a project. &CVS; stamps one +version of each file with the tag, so when you checkout or +update to a specific tag, you will get always the same file versions; +therefore, as opposed to branches, tags are not dynamic: you cannot develop a +tag. Tags are useful to mark releases, big changes in the code, &etc; +</para> + +<para> +When you are developing or following the development of a software project, +you do not necessarily work with the main branch all the time. After a release, +you may want to stay with the released branch for a while, to enjoy its relative +stability, fix bugs, translate the sources, &etc; To do all that, you have to +update to the released branch. All your files will be updated to the latest +version of the files in that branch. After updating, all your new commits will +be uploaded to the new branch as well. +</para> + +<para> +Also, if you want to track a bug that was reported +against a past tagged release, &CVS; offers you the possibility to retrieve the +software as it was released, by updating to that tag. Besides, if you want to +fetch a past version of your project, you can update your working copy to a +specific date. This may be useful if an error was introduced in the project +between two releases, and you have an opinion on when that was. When you update +to a date or tag, the versions of your files will be the same as the versions +in that specific date or the versions stamped by that tag. +</para> + +<warning><para> +Before updating to a different branch or tag, make sure you committed all your +changes to the branch you are working with. If your are not ready to +commit your changes, but do not want to discard them, do not update to the new +branch, as you may lose your changes. As an alternative, you can do a new +<link linkend="checkingout">checkout</link>, to work in parallel with +both versions. +</para></warning> + +<figure id="screenshot-updatetag" float="1"> +<title>A screenshot of &cervisia;'s update to tag dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="updatetag.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s update to tag dialog</phrase></textobject> +</mediaobject> +</figure> + +<variablelist> +<varlistentry> +<term><guilabel>Update to branch</guilabel></term> +<listitem><para> +Select this option to update to a branch. Enter the name of the branch in the +drop down text box (or press the <guilabel>Fetch List</guilabel> button to +retrieve the list of branches from the &CVS; server, and select the one you want +in the drop down list). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Update to tag</guilabel></term> +<listitem><para> +Select this option to update to a tag. Enter the name of the tag in the +drop down text box (or press the <guilabel>Fetch List</guilabel> button to +retrieve the list of tags from the &CVS; server, and select the one you want +in the drop down list). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Update to date</guilabel></term> +<listitem><para> +Select this option to update to a date. In the field below, you can enter a wide +variety of date formats. One possible format is <literal>yyyy-mm-dd</literal> +where <literal>yyyy</literal> is the year, <literal>mm</literal> is the month +(numerically) and <literal>dd</literal> is the day. Alternatives are some +English phrases like <literal>yesterday</literal> or <literal>2 weeks +ago</literal>. +</para></listitem> +</varlistentry> + +</variablelist> + +<note><para> +Updating to a tag or date make them 'sticky', &ie; you can not commit +further modifications on that files (unless the tag is a branch tag). In order +to get back to the main branch, use the menu item +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Update to +HEAD</guimenuitem></menuchoice>. +</para></note> + +<para> +The comand issued to update to a branch or tag is: +<screen><command>cvs update -r <replaceable>tag</replaceable></command></screen> +</para> + +<para> +The command issued to update to a date is: +<screen><command>cvs update -D <replaceable>date</replaceable></command></screen> +</para> + +<para> +The command issued to update to the main branch (HEAD) is: +<screen><command>cvs update <option>-A</option></command></screen> +</para> + +</sect1> + + +<sect1 id="taggingbranching"> +<title>Tagging and Branching</title> + +<para> +We discuss here only the technical aspects of tagging and branching. If you +are only a <emphasis>user</emphasis>, not the administrator of the repository, +you will probably not be confronted with the problem. If however you are your +own administrator, you should first read about the non-technical problems that +accompany branching, in order to get an impression of how time-consuming and +error-prone maintaining different branches of a project can be. The appendix +includes some references about this topic. +</para> + +<para> +Simple tagging is something you usually do when a release is made, so that you +can at any time easily get back to the project state at that time. Tags are +usually given a name consisting of the project name and the version +number. For example, &cervisia; 1.0 is available under the tag +<literal>CERVISIA_1_0</literal>. &cervisia; enforces &CVS;'s strict rules +about what constitutes valid tag name. It must begin with a letter and may +contain letters, digits, hyphens and underscores. +</para> + +<para> +Normally, you will want to tag the whole project (although &CVS; of course +allows you to tag only a subset). To this end, mark the toplevel folder in +the view and choose +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Tag/Branch</guimenuitem></menuchoice>. +Now enter the name of the tag, press <keycap>Return</keycap> and you are done. +</para> + +<para> +Creating a branch is not significantly more difficult: In the tag dialog, +check the box <guibutton>Create branch with this tag</guibutton>. You can also +delete an existing tag: Choose +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Delete +Tag</guimenuitem></menuchoice> in the main view. +</para> + +<para> +Another aspect of branching is the merging of modifications from a branch to +the current branch. If you are going to do this, choose +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Merge...</guimenuitem></menuchoice>. +The dialog that appears now gives you two options: +</para> + +<para> +Either you may merge all modifications done on a branch to the current +branch. In that case, check the box <guibutton>Merge from branch</guibutton> +and fill in the branch you want to merge from. &cervisia; will then execute +the command +</para> + +<para> +<screen><command>cvs update <option>-j</option> <replaceable>branchtag</replaceable></command></screen> +</para> + +<para> +The other possibility is that you want to merge only the modifications made +between two tags on a branch. This usually happens when you merge from the +same branch to the trunk several times. In that case, check the box +<guibutton>Merge modifications</guibutton> and enter (in the correct order) +the two relevant tags. This will result in a command +</para> + +<para> +<screen><command>cvs update <option>-j</option> <replaceable>branchtag1</replaceable> <option>-j</option> <replaceable>branchtag2</replaceable></command></screen> +</para> + +</sect1> + + +<sect1 id="watches"> +<title>Using Watches</title> + +<para> +A watch is the conventional name for &CVS;'s feature to notify users of the +repository whenever a file has been changed or a developer has started editing +a file. The usage of watches requires that the file +<filename><envar>$CVSROOT</envar>/CVSROOT/notify</filename> has been set up +properly. This is not discussed here; if you need further information on the +setup from the administrator's point of view, read one of the books listed in +the appendix. +</para> + +<para> +&cervisia;'s main support of watches are six menu items. +</para> + +<para> +In order to add a watch to one or several files, use +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Add +Watch...</guimenuitem></menuchoice>. In the dialog you get, you can choose to +get notified for any of the types of events that &CVS; supports. For example, +if you only want to get notified when a file is committed, check the boxes +<guibutton>Only</guibutton> and <guibutton>Commits</guibutton>. If you want to +get notified about any event related to the marked files, check the box +<guibutton>All</guibutton>. The command line used when you accept the dialog +is +</para> + +<para> +<screen><command>cvs watch add -a commit <replaceable>file names</replaceable></command></screen> +</para> + +<para> +or with a similar option, depending on the events you chose to watch. +</para> + +<para> +If you are not interested in some files anymore, you can remove your watches on +them. To this end, use +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Remove +Watch...</guimenuitem></menuchoice>. In the dialog you get here, the same +options are offered as in the form you filled out when adding the watch. When +you confirm this dialog, &cervisia; issues the command +</para> + +<para> +<screen><command>cvs watch remove <replaceable>file names</replaceable></command></screen> +</para> + +<para> +possibly with an option <option>-a</option> for the chosen events. +</para> + +<para> +Finally, you can get a list of the people who are watching a couple of +files. Choose <menuchoice><guimenu>Advanced</guimenu><guimenuitem>Show +Watchers</guimenuitem></menuchoice>. Using this menu item will result in a +command +</para> + +<para> +<screen><command>cvs watchers <replaceable>file names</replaceable></command></screen> +</para> + +<para> +In the normal usage scenario of &CVS;, each developer works separately in his +checked out sandbox. When he wants to modify some file, he can just open it in +his editor and start working on it. Nobody else will know about this work +until the file gets committed. +</para> + +<para> +For some developer groups, this is not the preferred model of +cooperation. They want to get notified about someone working on a file +<emphasis>as soon as</emphasis> he starts with it. This can be achieved by some +further &CVS; commands. Before you start editing a file, select it in +&cervisia;'s main window and choose +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Edit</guimenuitem></menuchoice>. +This will execute the command +</para> + +<para> +<screen><command>cvs edit <replaceable>file names</replaceable></command></screen> +</para> + +<para> +This will send out a notification to everyone who has set an +<literal>edit</literal> watch on this file. It will also register you as an +<emphasis>editor</emphasis> of the file. You can obtain a list of all editors +of a certain file by using +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Show +Editors</guimenuitem></menuchoice>. This is equivalent to typing on the +command line +</para> + +<para> +<screen><command>cvs editors <replaceable>file names</replaceable></command></screen> +</para> + +<para> +An editing session is automatically ended when you commit the affected file. +At that moment, an <literal>unedit</literal> notification gets sent out to all +people who have registered a respective watch on the file. Of course, +sometimes you may not want to commit the file, but abort the editing session +and revert to the previous version of the file. This is done by using +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Unedit</guimenuitem></menuchoice>. +Note that &cervisia; will not ask you for confirmation; that means if you use +this menu item, all your work done since you used +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Edit</guimenuitem></menuchoice> +will be lost. Precisely, &cervisia; uses the command line +</para> + +<para> +<screen><command>echo y | cvs unedit <replaceable>file names</replaceable></command></screen> +</para> + +<para> +So far, we have only the discussed the case where edits and unedits are used +voluntarily be the developers. In addition &CVS; supports a model which +<emphasis>enforces</emphasis> the usage of these commands. The responsible +command to switch to this model is <command>cvs watch on</command> which we +will not explain further because it is mostly used by the administrator of the +repository. However, the important point from the developer's point of view is +that when the project enforces edits, working copies are checked out +<emphasis>readonly</emphasis>. That means you cannot edit a file by default +(unless you use tricks like <command>chmod</command>). Only when you use +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Edit</guimenuitem></menuchoice>, +the file becomes writable. It is made read-only again when you commit the file +or use +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Unedit</guimenuitem></menuchoice>. +</para> + +<para> +&cervisia;'s editor interface helps you with projects that enforce watches +also in a different way. If you just started an editor with a readonly file +by double-clicking on it or by using +<menuchoice><guimenu>File</guimenu><guimenuitem>Edit</guimenuitem></menuchoice>, +you would not be able to save your modifications later. This has of course a +reason: Whenever you want to change a file, you should run <command>cvs +edit</command> before, so that all people watching the file get a notification +that you are working on it. +</para> + +<para> +In such a case, it is advisable to check the option +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Do cvs edit Automatically +When Necessary</guimenuitem></menuchoice>. Now, whenever you edit a file by +double-clicking it, &cervisia; will run <command>cvs edit</command> before the +editor is actually executed. Then you can edit your file as usual. When you +have finished your work, commit your files, and the committed files are +read-only again. +</para> + +</sect1> + + +<sect1 id="locking"> +<title>Locking</title> + +<para> +The development model usually followed when &CVS; is used is called +<emphasis>unreserved checkouts</emphasis>. Each developer has his own sandbox +where he can edit files as he likes. If when the watch features - like +<command>cvs edit</command> - are used, multiple developers can work on files +synchronously. Changes done by a different developer are merged into the local +sandbox when an update is performed. +</para> + +<para> +Other revision control systems - like <acronym>RCS</acronym> and +<application>SourceSafe</application> use a different model. When a developer +wants to a edit a file, he has to <emphasis>lock</emphasis> it. Only one +developer at a time can a lock a file. When he has finished editing, the lock +is released. On the one hand, with this model, conflicts can never happen. On +the other hand, two developers can not work on the same file at the same time, +even when their changes do not affect each other. This can be a bottleneck. +We are not going to discuss the organizational benefits of both approaches. +Nevertheless we mention that although &CVS; has some support for locking, it is +not the preferred way of working with &CVS;. You should not use these features +unless you are sure that your project manager allows them. +</para> + +<para> +With &cervisia;, you lock files as follows. Select the desired files in the +main view. Then choose +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Lock</guimenuitem></menuchoice>. +This runs the command +</para> + +<para> +<screen><command>cvs admin -l <replaceable>file names</replaceable></command></screen> +</para> + +<para>The reverse effect is achieved by using +<menuchoice><guimenu>Advanced</guimenu><guimenuitem>Unlock</guimenuitem></menuchoice>. +This runs the command</para> + +<para> +<screen><command>cvs admin -u <replaceable>file names</replaceable></command></screen> +</para> + +</sect1> + +</chapter> + + +<chapter id="customization"> +<title>Customizing &cervisia;</title> + +<para> +&cervisia; can be customized in various ways to your needs and +preferences. Some options which you may want to change regularly are directly +available in the <guimenu>Settings</guimenu> menu. Others are united in a common +dialog which is available via +<menuchoice><guimenu>Option</guimenu><guimenuitem>Settings...</guimenuitem></menuchoice>. +</para> + + +<sect1 id="customize-general"> +<title>General</title> + +<variablelist> + +<varlistentry id="customize-username"> +<term><guilabel>User name for the ChangeLog editor:</guilabel></term> +<listitem><para> +Whenever you use the menu item +<menuchoice><guimenu>File</guimenu><guimenuitem>Insert ChangeLog +Entry...</guimenuitem></menuchoice>, a new ChangeLog entry is generated with +the current date and your username. Normally, it is considered good style to +insert your full name and your email address into each of your ChangeLog +entries. &cervisia; add automatically the full name and email address +entered here. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-cvspath"> +<term><guilabel>Path to cvs executable, or 'cvs':</guilabel></term> +<listitem><para> +Here you can set the name (or path) to the <command>cvs</command> command +line client. By default, the &CVS; executable found in your <envar>$PATH</envar> is +used by &cervisia;. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="customize-diff"> +<title>Diff Viewer</title> + +<variablelist> + +<varlistentry id="customize-context"> +<term><guilabel>Number of context lines in the diff dialog:</guilabel></term> +<listitem><para> +For the diff dialog, &cervisia; uses the option <option>-U</option> to +<command>diff</command>. This lets <command>diff</command> show only a limited +number of lines around each difference region (context lines). Here you can set +the argument to <option>-U</option>. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-diffopt"> +<term><guilabel>Additional options for cvs diff:</guilabel></term> +<listitem><para> +Here you can add additional arguments to the <command>diff</command>. A +popular example is <option>-b</option> which lets <command>diff</command> +ignore changes in the amount of whitespace. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-tabwidth"> +<term><guilabel>Tab width in diff dialog:</guilabel></term> +<listitem><para> +In the diff dialog, tab characters present in your file or in the output +of the <command>diff</command> command are expanded into a fixed number of +space characters. By default, each tab is replaced by eight spaces, but here +you can setup a different number. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-difffrontend"> +<term><guilabel>External diff frontend:</guilabel></term> +<listitem><para> +When you use any of the features which show the diff dialog, like +<menuchoice><guimenu>View</guimenu><guimenuitem>Difference to +Repository...</guimenuitem></menuchoice>, &cervisia; invokes its internal diff +frontend. If you prefer a different one, like +<application>Kompare</application>, <application>TkDiff</application>, or +<application>xxdiff</application>, enter its file name and path here. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="customize-status"> +<title>Status</title> + +<variablelist> + +<varlistentry id="customize-startstatus-remote"> +<term><guilabel>When opening a sandbox from a remote repository, start a +File->Status command automatically</guilabel></term> +<listitem><para> +When you check this option, the +<menuchoice><guimenu>File</guimenu><guimenuitem>Status</guimenuitem></menuchoice> +command is started whenever you open a remote sandbox. This command may need some +time and also needs a connection to the server for remote repositories (making +it unusable for offline usage). +</para></listitem> +</varlistentry> + +<varlistentry id="customize-startstatus-local"> +<term><guilabel>When opening a sandbox from a local repository, start a +File->Status command automatically</guilabel></term> +<listitem><para> +When you check this option, the +<menuchoice><guimenu>File</guimenu><guimenuitem>Status</guimenuitem></menuchoice> +command is started whenever you open a local sandbox. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="customize-advanced"> +<title>Advanced</title> + +<variablelist> + +<varlistentry id="customize-timeout"> +<term><guilabel>Timeout after which a progress dialog appears (in ms):</guilabel></term> +<listitem><para> +Practically all &CVS; commands started in a sandbox which belongs to a remote +repository need a connection to the &CVS; server. This is affected by delays +from the network connection or a high load on the server. For this reason, for +commands like <menuchoice><guimenu>View</guimenu><guimenuitem>Difference to +Repository...</guimenuitem></menuchoice> &cervisia; opens a dialog which +indicates that the command is still running and which allows you to abort +it. Furthermore, this dialog is used to show you error messages from &CVS;. As +this dialog may become annoying after some time, it is shown only after a +certain timeout which is 4 seconds by default. Here you can change this value. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-compression"> +<term><guilabel>Default compression level:</guilabel></term> +<listitem><para> +The <command>cvs</command> client compresses files and patches when they are +transferred over a network. With the command line option <option>-z</option>, +the compression level can be set. You can setup &cervisia; to use this option +by configuring the level here. The value set here is used only as a default; +additionally there is a per-repository setting available in +<menuchoice><guimenu>Repository</guimenu><guimenuitem>Repositories...</guimenuitem></menuchoice>. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-sshagent"> +<term><guilabel>Utilize a running or start a new ssh-agent process</guilabel></term> +<listitem><para> +Check this box if you use <link linkend="rsh">ext (rsh) repositories</link>, +the &ssh; remote shell to communicate with the repository and +<application>ssh-agent</application> to manage your keys. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + + +<sect1 id="customize-look"> +<title>Look'n'feel</title> + +<variablelist> + +<varlistentry id="customize-protocolfont"> +<term><guilabel>Font for protocol window...</guilabel></term> +<listitem><para> +Press this button to open the <guilabel>Set Font</guilabel> dialog, to set the +font used in the protocol window (this is the window showing the +output of the <command>cvs</command> client). +</para></listitem> +</varlistentry> + +<varlistentry id="customize-annotatefont"> +<term><guilabel>Font for annotate view...</guilabel></term> +<listitem><para> +Press this button to open the <guilabel>Set Font</guilabel> dialog, to set the +font used in the <link linkend="annotate">annotate view</link>. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-difffont"> +<term><guilabel>Font for diff view...</guilabel></term> +<listitem><para> +Press this button to open the <guilabel>Set Font</guilabel> dialog, to set the +font used in <link linkend="diff">diff dialogs</link>. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-colors"> +<term><guilabel>Colors</guilabel></term> +<listitem><para> +Press the colored buttons to open the <guilabel>Select Color</guilabel> dialog, +to set the color used for <guilabel>Conflict</guilabel>, <guilabel>Local +Change</guilabel>, or <guilabel>Remote Change</guilabel>, in the main view or +<guilabel>Diff change</guilabel>, <guilabel>Diff insertion</guilabel>, or +<guilabel>Diff deletion</guilabel>, in &cervisia;'s built-in diff frontend. +</para></listitem> +</varlistentry> + +<varlistentry id="customize-splitter"> +<term><guilabel>Split main window horizontally</guilabel></term> +<listitem><para> +&cervisia;'s main window is normally split vertically into a window with +the file tree above and one with the &CVS; output below; alternatively, you can +arrange them horizontally. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> +</chapter> + + +<chapter id="appendix"> +<title>Appendix</title> + +<sect1 id="ignoredfiles"> +<title>Ignored Files</title> + +<para> +In its main file tree, &cervisia; does not display all files which are +actually there. This is analog to <command>cvs</command> itself and helps to +avoid clutter caused by uninteresting stuff like object files. &cervisia; +tries to mimic <command>cvs</command>'s behavior as close as possible, +i.e. it gets ignore lists from the following sources: +</para> + +<itemizedlist> + +<listitem><para> +A static list of entries which includes things like <literal +role="extension">*.o</literal> and <filename>core</filename>. For details, +see the &CVS; documentation. +</para></listitem> +<listitem><para> +The file <filename><envar>$HOME</envar>/.cvsignore</filename>. +</para></listitem> + +<listitem><para> +The environment variable <envar>$CVSIGNORE</envar>. +</para></listitem> +<listitem><para> +The <filename>.cvsignore</filename> file in the respective folder. +</para></listitem> + +</itemizedlist> + +<para> +<command>cvs</command> itself additionally looks up entries in +<filename><envar>$CVSROOT</envar>/CVSROOT/cvsignore</filename>, but this is a +file on the server, and &cervisia; should be able to start up offline. If you +are working with a group that prefers to use an ignore list on the server, +it's probably a good idea to take a look which patterns are listed there and +to put them into the <filename>.cvsignore</filename> file in your home +folder. +</para> + +</sect1> + + +<sect1 id="information"> +<title>Further Information and Support</title> + +<itemizedlist> + +<listitem><para> +&CVS; comes with a complete set of documentation in the form of info pages, +known as "The Cederqvist". If it is properly installed, you get browse it by +typing in <userinput>info:/cvs</userinput> into the locationbar of +<application>kdehelp</application>, <application>khelpcenter</application> +resp. Alternative, you can just choose +<menuchoice><guimenu>Help</guimenu><guimenuitem>CVS +Info</guimenuitem></menuchoice> in &cervisia;. An on-line HTML version of the +Cederqvist is available <ulink +url="http://cvshome.org/docs/manual/cvs.html">on the web</ulink>. +</para> + +<para> +As this book is maintained together with &CVS;, it is normally the most +up-to-date reference; nevertheless, considering other documentation +for learning to use &CVS; is recommended, in particular the following. +</para></listitem> + +<listitem><para> +Karl Fogel has written the excellent book <ulink +url="http://cvsbook.red-bean.com/index.html">Open Source Development with +CVS</ulink>. About half of this book is about the development process of Open +Source software. The other half is a technical documentation of +&CVS;. Thankfully, the technical part of the book has been made freely +redistributable under the GPL, so that you can download a HTML version of +it. A list of errata is available on the webpage mentioned above. +</para></listitem> + +<listitem><para> +&CVS; issues are discussed on a dedicated <ulink +url="http://mail.gnu.org/mailman/listinfo/info-cvs">mailing list</ulink>. +</para></listitem> + +<listitem><para> +There is USENET group <literal>comp.software.config-mgmt</literal> dedicated +to configuration management in general. &CVS; is only marginally a topic in +this group, but nevertheless it may be interesting for discussing merits of +various revision control systems compared to &CVS;. +</para></listitem> + +<listitem><para> +Last but not least, there is a (low traffic) <ulink +url="http://lists.sourceforge.net/mailman/listinfo/cervisia-user">&cervisia; +mailing list</ulink>. +</para></listitem> + +</itemizedlist> + +</sect1> + + +<sect1 id="commandreference"> +<title>Command Reference</title> + +<!-- File Menu --> +<sect2 id="menufile"> + +<title>The File Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Open Sandbox...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens a sandbox in the main window. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Recent sandboxes</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens one of the sandboxes that were in use recently. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Insert ChangeLog Entry...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens the ChangeLog editor, prepared such that you can add a new entry with +the current date. See <xref linkend="committingfiles" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo><keycap>&Ctrl;</keycap><keycap>U</keycap></keycombo></shortcut> +<guimenu>File</guimenu><guimenuitem>Update</guimenuitem> +</menuchoice></term> +<listitem><para> +Runs 'cvs update' on selected files and changes the status and revision +numbers in the listing accordingly. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>F5</keycap></shortcut> +<guimenu>File</guimenu><guimenuitem>Status</guimenuitem> +</menuchoice></term> +<listitem><para> +Runs 'cvs -n update' on selected files and changes the status and revision +numbers in the listing accordingly. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Edit</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens the selected file in KDE's default editor for the selected file's type. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Resolve...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens a dialog for the selected file which allows +you to resolve merge conflicts in it. See <xref linkend="resolvingconflicts" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>#</keycap></shortcut> +<guimenu>File</guimenu><guimenuitem>Commit...</guimenuitem> +</menuchoice></term> +<listitem><para> +Allows you to commit the selected files. See <xref linkend="committingfiles" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>+</keycap></shortcut> +<guimenu>File</guimenu><guimenuitem>Add to Repository...</guimenuitem> +</menuchoice></term> +<listitem><para> +Allows you to add the selected files to the repository. See <xref linkend="addingfiles" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>File</guimenu><guimenuitem>Add Binary...</guimenuitem> +</menuchoice></term> +<listitem><para> +Allows you to add the selected files to the repository as binaries +(<command>cvs add<option>-kb</option></command>). See <xref linkend="addingfiles" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>-</keycap></shortcut> +<guimenu>File</guimenu><guimenuitem>Remove from Repository...</guimenuitem> +</menuchoice></term> +<listitem><para> +Allows you to remove the selected files from the repository. See <xref linkend="removingfiles" />. +</para></listitem> +</varlistentry> + +<!--TODO: add the revert action to the working with files chapter --> + +<varlistentry> +<term><menuchoice><guimenu>File</guimenu><guimenuitem>Revert</guimenuitem> +</menuchoice></term> +<listitem><para> +Discards any local changes you have made to the selected files and reverts to +the version in the repository (Option <option>-C</option> to <command>cvs +update</command>). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo><keycap>&Ctrl;</keycap><keycap>Q</keycap></keycombo></shortcut> +<guimenu>File</guimenu><guimenuitem>Exit</guimenuitem> +</menuchoice></term> +<listitem><para>Quits &cervisia;. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<!-- View Menu --> +<sect2 id="menuview"> + +<title>The View Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>Escape</keycap></shortcut> +<guimenu>View</guimenu><guimenuitem>Stop</guimenuitem> +</menuchoice></term> +<listitem><para> +Aborts any running subprocesses. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo><keycap>&Ctrl;</keycap><keycap>L</keycap></keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Browse Log...</guimenuitem> +</menuchoice></term> +<listitem><para> +Shows the log browser of the selected file versions. See <xref linkend="browsinglogs" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo><keycap>&Ctrl;</keycap><keycap>A</keycap></keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Annotate...</guimenuitem> +</menuchoice></term> +<listitem><para> +Shows an annotated view of the selected file, i.e. a view where you +can for each line see which author modified it last. See <xref linkend="annotate" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo><keycap>&Ctrl;</keycap><keycap>D</keycap></keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Difference to Repository (BASE)...</guimenuitem> +</menuchoice></term> +<listitem><para> +Shows the differences between the selected file in the sandbox +and the revision you last updated (BASE). See <xref linkend="diff" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo><keycap>&Ctrl;</keycap><keycap>H</keycap></keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Difference to Repository (HEAD)...</guimenuitem> +</menuchoice></term> +<listitem><para> +Shows the differences between the selected file in the sandbox +and the revision you last updated (HEAD). See <xref linkend="diff" />. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Last Change...</guimenuitem> +</menuchoice></term> +<listitem><para> +Shows the differences between the revision of the selected +file you last updated (BASE) and the revision before. See <xref linkend="diff" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>History...</guimenuitem> +</menuchoice></term> +<listitem><para> +Shows the &CVS; history as reported by the server. See <xref linkend="browsinghistory" />. +</para></listitem> +</varlistentry> + +<!--TODO: add hide menus to mainscreen section--> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Hide All Files</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether only folders are shown in the main tree view. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Hide Unmodified Files</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether unknown and up to date files are hidden in the main tree view. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Hide Removed Files</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether removed files are hidden in the main tree view. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Hide Non-CVS Files</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether files not in CVS are hidden in the main tree view. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Hide Empty Folders</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether folders without visible entries are hidden in the main tree view. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Unfold File Tree</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens all branches in the file tree so that you can +see all files and folders. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Fold File Tree</guimenuitem> +</menuchoice></term> +<listitem><para> +Closes all branches in the file tree. See <xref linkend="mainscreen" />. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<!-- Advanced Menu --> +<sect2 id="menuadvanced"> + +<title>The Advanced Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Tag/Branch...</guimenuitem> +</menuchoice></term> +<listitem><para> +Tags or branches the selected files. See <xref linkend="taggingbranching" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Delete Tag...</guimenuitem> +</menuchoice></term> +<listitem><para> +Removes a given tag from the selected files. See <xref linkend="taggingbranching" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Update to Tag/Date...</guimenuitem> +</menuchoice></term> +<listitem><para> +Brings the selected files to a given tag or date, +making it sticky. See <xref linkend="updatingto" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Update to HEAD...</guimenuitem> +</menuchoice></term> +<listitem><para> +Brings the selected files to the respective HEAD revision. See <xref linkend="updatingto" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Merge...</guimenuitem> +</menuchoice></term> +<listitem><para> +Merges either a given branch or the modifications +between two tags into the selected files. See <xref linkend="taggingbranching" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Add Watch...</guimenuitem> +</menuchoice></term> +<listitem><para> +Adds a watch for a set of events on the selected files. See <xref linkend="watches" />. +</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Remove Watch...</guimenuitem> +</menuchoice></term> +<listitem><para>Removes a watch for a set of events from the selected files. See <xref linkend="watches" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Show Watchers</guimenuitem> +</menuchoice></term> +<listitem><para> +Lists the watchers of the selected files. See <xref linkend="watches" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Edit</guimenuitem> +</menuchoice></term> +<listitem><para> +Runs <command>cvs edit</command> on the selected files. See <xref linkend="watches" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Unedit</guimenuitem> +</menuchoice></term> +<listitem><para> +Runs <command>cvs unedit</command> on the selected files. See <xref linkend="watches" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Show Editors</guimenuitem> +</menuchoice></term> +<listitem><para> +Runs <command>cvs editors</command> on the selected files. See <xref linkend="watches" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Lock</guimenuitem> +</menuchoice></term> +<listitem><para> +Locks the selected files. See <xref linkend="locking" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Unlock</guimenuitem> +</menuchoice></term> +<listitem><para> +Unlocks the selected files. See <xref linkend="locking" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Advanced</guimenu><guimenuitem>Create Patch Against Repository...</guimenuitem> +</menuchoice></term> +<listitem><para> +Creates a patch from the modifications in your sandbox. See <xref linkend="creatingpatches" />. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<!-- Repository Menu --> +<sect2 id="menurepository"> + +<title>The Repository Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Repository</guimenu><guimenuitem>Create...</guimenuitem> +</menuchoice></term> +<listitem><para>Opens a dialog which allows you to create a new local +repository. See <xref linkend="accessing-repository" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Repository</guimenu><guimenuitem>Checkout...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens a dialog which allows you to checkout +a module from a repository. See <xref linkend="checkingout" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Repository</guimenu><guimenuitem>Import...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens a dialog which allows you to import +a package into the repository. See <xref linkend="importing" />. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Repository</guimenu><guimenuitem>Repositories...</guimenuitem> +</menuchoice></term> +<listitem><para>Configures a list of repositories you often use +and how to access them. See <xref linkend="accessing-repository" />. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<!-- Settings Menu --> +<sect2 id="menuoptions"> +<title>The Settings Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Show Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether the toolbar is displayed. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Create Folders on Update</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether updates create folders in the sandbox which were not +there before (Option <option>-d</option> to <command>cvs update</command>). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Prune Empty Folders on Update</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether updates remove empty folders in the sandbox. (Option +<option>-P</option> to <command>cvs update</command>). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Update Recursively</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether updates are recursive (Option <option>-r</option> to +<command>cvs update</command>). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Commit and Remove Recursively</guimenuitem> +</menuchoice></term> +<listitem><para>Determines whether commits and removes are recursive +(Option <option>-r</option> to <command>cvs add</command>, +<command>cvs remove</command> resp.). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Do cvs edit Automatically When Necessary</guimenuitem> +</menuchoice></term> +<listitem><para> +Determines whether <command>cvs edit</command> is executed automatically +whenever you edit a file. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens a dialog for configuring keybindings. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens a dialog for configuring &cervisia;'s toolbars. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure Cervisia...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens a dialog for customizing &cervisia;. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<!-- Help --> +<sect2 id="menuhelp"> +<title>The Help Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>F1</keycap></shortcut> +<guimenu>Help</guimenu><guimenuitem>Handbook</guimenuitem> +</menuchoice></term> +<listitem><para> +Invokes the KDE Help system starting at the &cervisia; help pages. (this +document). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu><guimenuitem>Report Bug...</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens the Bug report dialog. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu> +<guimenuitem>About &cervisia;</guimenuitem> +</menuchoice></term> +<listitem><para> +This will display version and author information. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu><guimenuitem>About KDE</guimenuitem> +</menuchoice></term> +<listitem><para> +This displays the KDE version and other basic information. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu><guimenuitem>CVS Manual</guimenuitem> +</menuchoice></term> +<listitem><para> +Opens the &CVS; info pages in the KDE help system. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +</chapter> + + +<chapter id="credits-and-licenses"> +<title>Credits And Licenses</title> + +&underFDL; +&underGPL; + +</chapter> +</book> diff --git a/doc/cervisia/logtree.png b/doc/cervisia/logtree.png Binary files differnew file mode 100644 index 00000000..e8ad4b4d --- /dev/null +++ b/doc/cervisia/logtree.png diff --git a/doc/cervisia/mainview.png b/doc/cervisia/mainview.png Binary files differnew file mode 100644 index 00000000..232239bd --- /dev/null +++ b/doc/cervisia/mainview.png diff --git a/doc/cervisia/patch.png b/doc/cervisia/patch.png Binary files differnew file mode 100644 index 00000000..3a5d8482 --- /dev/null +++ b/doc/cervisia/patch.png diff --git a/doc/cervisia/popup.png b/doc/cervisia/popup.png Binary files differnew file mode 100644 index 00000000..c95ce8db --- /dev/null +++ b/doc/cervisia/popup.png diff --git a/doc/cervisia/repositories.png b/doc/cervisia/repositories.png Binary files differnew file mode 100644 index 00000000..ea52aa53 --- /dev/null +++ b/doc/cervisia/repositories.png diff --git a/doc/cervisia/resolve.png b/doc/cervisia/resolve.png Binary files differnew file mode 100644 index 00000000..1f9b2582 --- /dev/null +++ b/doc/cervisia/resolve.png diff --git a/doc/cervisia/updatetag.png b/doc/cervisia/updatetag.png Binary files differnew file mode 100644 index 00000000..c8802ef3 --- /dev/null +++ b/doc/cervisia/updatetag.png diff --git a/doc/kapptemplate/Makefile.am b/doc/kapptemplate/Makefile.am new file mode 100644 index 00000000..07fc0b90 --- /dev/null +++ b/doc/kapptemplate/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG=en +KDE_MANS=AUTO diff --git a/doc/kapptemplate/man-kapptemplate.1.docbook b/doc/kapptemplate/man-kapptemplate.1.docbook new file mode 100644 index 00000000..92eff12e --- /dev/null +++ b/doc/kapptemplate/man-kapptemplate.1.docbook @@ -0,0 +1,115 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email></email></author> +<date>April 12, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>kapptemplate</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>kapptemplate</command></refname> +<refpurpose>Creates a framework to develop a KDE application</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>kapptemplate</command> +<group><option>--noinit</option></group> +<group><option>--default</option></group> +<group><option>--full-app</option></group> +<group><option>--kpart-app</option></group> +<group><option>--kpart-plugin</option></group> +<group><option>--existing</option></group> +<group><option>--help</option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>kapptemplate</command> is a shell script that will create the necessary framework to develop various &kde; applications. It takes care of the autoconf/automake code as well as providing a skeleton and example of what the code typically looks like. </para> + +<para>This utility is part of the &kde; Software Development Kit. </para> + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<title>General Options</title> +<varlistentry> +<term><option>--help</option></term> +<listitem><para>Display a full summary of options. </para></listitem> +</varlistentry> +<varlistentry> +<term><option>--no-init</option></term> +<listitem><para>Don't run <command>make</command> <option>-f</option> <parameter>Makefile.cvs</parameter></para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>--default</option></term> +<listitem><para>Use default values instead of prompting.</para></listitem> +</varlistentry> +</variablelist> + +<variablelist> +<title>Framework Types</title> +<varlistentry> +<term><option>--full-app</option></term> +<listitem><para>Create a full featured KDE application. </para></listitem> +</varlistentry> +<varlistentry> +<term><option>--kpart-app</option></term> +<listitem><para>Create a full featured KPart application.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>--kpart-plugin</option></term> +<listitem><para>Create a KPart plugin framework.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>--existing</option></term> +<listitem><para>Converting existing source to an automake/autoconf KDE framework.</para></listitem> +</varlistentry> +</variablelist> +</refsect1> + +<!-- The Following sections are optional, but recommended if they are +applicable. --> + +<refsect1> +<title>Files</title> + +<variablelist> +<varlistentry> +<term><filename>~/.kapptemplate</filename></term> +<listitem><para>Stores default values</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para><filename>$PREFIX/share/doc/kapptemplate</filename></para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para><command>kapptemplate</command> was written by &Kurt.Granroth; &Kurt.Granroth.mail;</para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> +</refsect1> + +</refentry> diff --git a/doc/kbabel/Makefile.am b/doc/kbabel/Makefile.am new file mode 100644 index 00000000..17a314c3 --- /dev/null +++ b/doc/kbabel/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/kbabel/TODO b/doc/kbabel/TODO new file mode 100644 index 00000000..916027bf --- /dev/null +++ b/doc/kbabel/TODO @@ -0,0 +1,4 @@ +KBabel documentation TODO: + +missing: +catman - find/replace dialogs diff --git a/doc/kbabel/back.png b/doc/kbabel/back.png Binary files differnew file mode 100644 index 00000000..2ffa9395 --- /dev/null +++ b/doc/kbabel/back.png diff --git a/doc/kbabel/bottom.png b/doc/kbabel/bottom.png Binary files differnew file mode 100644 index 00000000..caf4ea5a --- /dev/null +++ b/doc/kbabel/bottom.png diff --git a/doc/kbabel/catalogmanager.png b/doc/kbabel/catalogmanager.png Binary files differnew file mode 100644 index 00000000..48bbade3 --- /dev/null +++ b/doc/kbabel/catalogmanager.png diff --git a/doc/kbabel/catalogmanager_broken.png b/doc/kbabel/catalogmanager_broken.png Binary files differnew file mode 100644 index 00000000..d0948e92 --- /dev/null +++ b/doc/kbabel/catalogmanager_broken.png diff --git a/doc/kbabel/catalogmanager_missing.png b/doc/kbabel/catalogmanager_missing.png Binary files differnew file mode 100644 index 00000000..e0311068 --- /dev/null +++ b/doc/kbabel/catalogmanager_missing.png diff --git a/doc/kbabel/catalogmanager_needwork.png b/doc/kbabel/catalogmanager_needwork.png Binary files differnew file mode 100644 index 00000000..e31413d8 --- /dev/null +++ b/doc/kbabel/catalogmanager_needwork.png diff --git a/doc/kbabel/catalogmanager_nopot.png b/doc/kbabel/catalogmanager_nopot.png Binary files differnew file mode 100644 index 00000000..1e220bee --- /dev/null +++ b/doc/kbabel/catalogmanager_nopot.png diff --git a/doc/kbabel/catalogmanager_nopot_ok.png b/doc/kbabel/catalogmanager_nopot_ok.png Binary files differnew file mode 100644 index 00000000..50028c65 --- /dev/null +++ b/doc/kbabel/catalogmanager_nopot_ok.png diff --git a/doc/kbabel/catalogmanager_ok.png b/doc/kbabel/catalogmanager_ok.png Binary files differnew file mode 100644 index 00000000..f2b731a0 --- /dev/null +++ b/doc/kbabel/catalogmanager_ok.png diff --git a/doc/kbabel/catalogmanager_reload.png b/doc/kbabel/catalogmanager_reload.png Binary files differnew file mode 100644 index 00000000..e7aeaac5 --- /dev/null +++ b/doc/kbabel/catalogmanager_reload.png diff --git a/doc/kbabel/catman.docbook b/doc/kbabel/catman.docbook new file mode 100644 index 00000000..a55d46ec --- /dev/null +++ b/doc/kbabel/catman.docbook @@ -0,0 +1,214 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> --> +<!-- Uncomment the previous two lines to validate this document --> +<!-- standalone. Be sure to recomment them before attempting to --> +<!-- process index.docbook --> + +<chapter id="using-catalogmanager"> + +<chapterinfo> +<!-- Fill in this section if this document has a different author --> +<authorgroup> +<author> +<personname><firstname></firstname><surname></surname></personname> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</chapterinfo> + +<title>Using &catalogmanager;</title> +<anchor id="catalogmanager"/> + +<screenshot> +<screeninfo>Screenshot of &catalogmanager;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="snap_catalogmanager.png" format="PNG"/> +</imageobject> +<textobject><phrase>Screenshot of &catalogmanager;</phrase></textobject> +</mediaobject> +</screenshot> +<para> +The Catalog Manager merges two folders into one tree and displays +all the <acronym>PO</acronym> and <acronym>POT</acronym> files in +these folders. The display allows you to easily see if a new +template has been added or an old one has been removed. Some +information is shown along with each file name: total number of +entries, number of fuzzy entries, number of untranslated entries, the +date of the last revision and the last translator of the file. +</para> + +<important><para> +KBabel's Catalog Manager is meant for projects structured like KDE, +where the <acronym>POT</acronym> and <acronym>PO</acronym> files +share a same name, save the extensions. However this is not the +case of &GNU; projects and of many projects structured like &GNU; ones. +Typically in such projects, the <acronym>PO</acronym> file is named +following the language code and so is very different than the name +of the <acronym>POT</acronym> files. Also such projects have +one <acronym>POT</acronym> file sharing a directory with all its +translated <acronym>PO</acronym> files. Unfortunately, all these reasons +mean that the Catalog Manager is <emphasis>not</emphasis> suitable for +such projects. (See <ulink url="http://bugs.kde.org/show_bug.cgi?id=76495">KDE bug #76495</ulink>.) +</para></important> + +<para> +To make it easier for you to find files that need work or are +missing the status of each file is also displayed using an icon: +</para> + +<itemizedlist> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_ok.png" format="PNG"/> +</imageobject> +</inlinemediaobject> All the messages in this file are translated.</para> + </listitem> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_needwork.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +Some of the messages in this file are fuzzy or untranslated + </para> + </listitem> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_missing.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +This file does not exist in the folder of the <acronym>PO</acronym> files. + </para> + </listitem> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_broken.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +This file contains syntax errors. + </para> + </listitem> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_reload.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +Information about this file is being currently updated. When the update is +finished, it will get one of the icons listed above to reflect its state. + </para> + </listitem> +</itemizedlist> + +<para> +If an icon is marked with this icon +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_nopot.png" format="PNG"/> +</imageobject> +</inlinemediaobject>, like +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_nopot_ok.png" format="PNG"/> +</imageobject> +</inlinemediaobject>, +it indicates that this file or folder does not exist in the +folder of the <acronym>POT</acronym> files.</para> + +<para> You can mark or unmark a file by selecting <guimenuitem>Toggle +Marking</guimenuitem> in the context menu of a file.</para> + +<para>If you want to toggle or remove all markings in a folder, +press the right mouse button over the folder and select +<guimenuitem>Toggle Markings</guimenuitem> or <guimenuitem>Remove +Markings</guimenuitem>. The markings are automatically saved when +leaving &kbabel;.</para> + +<para>To open a file either double-click on the file, select +<menuchoice><guimenuitem>Open</guimenuitem></menuchoice> from the +context menu or press either <keycap>Return</keycap> or <keycombo +action="simul">&Ctrl;<keycap>O</keycap> </keycombo>.</para> + +<para>You can configure the &catalogmanager; by +<menuchoice><guimenu>Project</guimenu><guimenuitem> +Configure...</guimenuitem></menuchoice>. +See section <link linkend="preferences-project-settings">Project Settings</link> for more +details.</para> + +<sect1 id="catman-features"> +<title>&catalogmanager; Features</title> +<para> +Besides the main feature for opening the files in &kbabel; &catalogmanager; +supports number of other features for maintaining a tree of +<acronym>PO</acronym>-files. +</para> + +<sect2 id="catman-find"> +<title>Find and replace in multiple files</title> +<para> +One of the most requested features for &kbabel; was a possibility to search and replace in +multiple files at once. &catalogmanager; supports this feature with +a tight integration with &kbabel; +</para> +</sect2> + +<sect2 id="catman-statistics"> +<title>Statistics</title> +<para> +&catalogmanager; can show you a number of statistics about a single file +or about the whole folders. The statistics contain number of files, +how many of the files have their templates, how many templates are missing. +It also counts number of messages in the files and shows statistics about +how large parts of the messages are translated, fuzzy-translated or +untranslated. +</para> +</sect2> + +<sect2 id="catman-syntax"> +<title>Checking the syntax</title> +<para> +This allows you to check the syntax of multiple <acronym>PO</acronym>-files +using <command>msgfmt</command>. If a file fails this check, it cannot +be used for generating a <acronym>MO</acronym>-file for binary distribution. +Such an incorrect file will typically result in failing compilation of the package +the <acronym>PO</acronym>-file belongs to. +</para> +</sect2> + +<sect2 id="catman-commands"> +<title>User-defined commands</title> +<para> +Because &catalogmanager; cannot provide any functionality you would like +to use, you can extend it by defining your own commands. +</para> +<!-- ### TODO: we should lik to preferences-project-file-commands too --> +<para> +There are two sets of commands. One for folders and one for single files. +You can set them in <link +linkend="preferences-project-folder-commands">configuration dialog </link> and +access by pressing &RMB; on an entry in the file list.</para> +</sect2> + +</sect1> +</chapter> +<!-- +Local Variables: +mode: xml +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/kbabel/dbcan.png b/doc/kbabel/dbcan.png Binary files differnew file mode 100644 index 00000000..a8cf3080 --- /dev/null +++ b/doc/kbabel/dbcan.png diff --git a/doc/kbabel/dictionaries.docbook b/doc/kbabel/dictionaries.docbook new file mode 100644 index 00000000..a9e5ed70 --- /dev/null +++ b/doc/kbabel/dictionaries.docbook @@ -0,0 +1,517 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> --> +<!-- Uncomment the previous two lines to validate this document --> +<!-- standalone. Be sure to recomment them before attempting to --> +<!-- process index.docbook --> + +<chapter id="dictionaries"> + +<chapterinfo> +<!-- Fill in this section if this document has a different author --> +<authorgroup> +<author> +<personname><firstname></firstname><surname></surname></personname> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</chapterinfo> + +<title>Dictionaries</title> + +<para>&kbabel; has 3 modes which can be used to search translated +<acronym>PO</acronym> message strings:</para> + +<itemizedlist> + <listitem> + <para>Searching translation, using a translation database + </para> + </listitem> + <listitem> + <para>Rough translation + </para> + </listitem> + <listitem> + <para>&kbabeldict; + </para> + </listitem> +</itemizedlist> + +<sect1 id="database"> +<!-- FIXME: settings --> +<title>Translation database</title> + +<!-- ### TODO: only *one* file? Seems more to be four... --> +<para>Translation database allows you to store translations in a +database based on Berkeley Database IV, &ie; it is stored in a binary +file on your disk. The database guarantees fast searching in a large +number of translations.</para> + +<para>This mode is the one best integrated with &kbabel;. Besides +searching and rough translation it also supports the following +features:</para> + +<itemizedlist> +<listitem> +<para>Every new translation typed in the &kbabel; editor can be +automatically stored in the database.</para> +</listitem> +<listitem> +<para>This database can be used for <quote>diff</quote>-ing +<acronym>msgid</acronym>.</para> +</listitem> +</itemizedlist> + +<para>Of course, the more translations are stored in the database, the +more productive you can be. To fill the database, you can use the +<guilabel>Database</guilabel> tab in the preferences dialog or you can +turn on automatic addition of every translated messages on the same +tab.</para> + +<sect2 id="database-settings"> +<title>Settings</title> +<para> +You can configure this searching mode and how it should be used by selecting +<menuchoice> + <guisubmenu>Settings</guisubmenu> + <guisubmenu>Configure Dictionary</guisubmenu> + <guimenuitem>Translation Database</guimenuitem> +</menuchoice> +in &kbabel; menu. +</para> +<para> +The <guilabel>Generic</guilabel> tab contains general settings for searching in the +database. +</para> +<variablelist> + <varlistentry> + <term><guilabel>Search in whole database (slow)</guilabel></term> + <listitem> + <para> + Do not use <quote>good keys</quote>, search in the whole database. + This is slow, but will return the most precise results. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Search in list of "good keys" (best)</guilabel></term> + <listitem> + <para> + Use <quote>good keys</quote> strategy. This option will give you the + best tradeoff between speed and exact matching. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Return the list of "good keys" (fast)</guilabel></term> + <listitem> + <para> + Just return <quote>good keys</quote>, do not try to eliminate any more + texts. This is the fastest provided method, but can lead to a quite large + number of imprecise matches. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Case sensitive</guibutton></term> + <listitem> + <para> + Distinguish case of letters when searching the text. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Normalize white space</guibutton></term> + <listitem> + <para> + Skip unnecessary white space in the texts, so the searching will ignore small + differences of white space, ⪚ number of spaces in the text. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Remove context comment</guibutton></term> + <listitem> + <para> + Do not include context comments in search. You will want this to be turned on. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Character to be ignored</guilabel></term> + <listitem> + <para>Here you can enter characters, which should be ignored while searching. + Typical example would be accelerator mark, &ie; & for &kde; texts. + </para> + </listitem> + </varlistentry> + </variablelist> +<para> +The <guilabel>Search</guilabel> tab contains finer specification for searching the text. +You can define how to search and also allows to use another special way of searching +called <emphasis><guilabel>Word substitution</guilabel></emphasis>. By substituting +one or two words the approximate text can be found as well. For example, assume you +are trying to find the text <userinput>My name is Andrea</userinput>. +</para> +<variablelist> + <varlistentry> + <term><guilabel>Equal</guilabel></term> + <listitem> + <para> + Text from database matches if it is the same as the searched string. In our example it can + be <emphasis>My name is &Andrea</emphasis> (if & is set as ignored character + in <guilabel>Characters to be ignored</guilabel> on <guilabel>Generic</guilabel> tab). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Query is contained</guilabel></term> + <listitem> + <para> + Text from database matches if the searched string is contained in it. For our example it can + be <emphasis>My name is Andrea, you know?</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Query contains</guilabel></term> + <listitem> + <para> + Text from database matches if the searched string contains it. For our example it can + be <emphasis>Andrea</emphasis>. You can use this for enumerating the possibilities to + be found. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Regular Expression</guibutton></term> + <listitem> + <para> + Consider searched text as a regular expression. This is mainly used for + &kbabeldict;. You can hardly expect regular expressions in PO files. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Use one word substitution</guibutton></term> + <listitem> + <para> + If the query text contains less words than specified below, it also + tries to replace one of the words in the query. In our example it will + find <emphasis>Your name is Andrea</emphasis> as well. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Max number of words in the query</guibutton></term> + <listitem> + <para> + Maximal number of words in a query to enable one word substitution. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Local characters for regular expressions</guilabel></term> + <listitem> + <para> + Characters to be considered part of regular expressions. + </para> + </listitem> + </varlistentry> + </variablelist> +<note> +<para> +Two-word substitution is not implemented yet. +</para> +</note> +</sect2> + +<sect2 id="database-fill"> +<title>Filling the database</title> +<para> +The <guilabel>Database</guilabel> tab allows to define where is the database stored on +disk (<guilabel>Database folder</guilabel>) and if it should be used for automatic +storing of the new translations (<guibutton>Auto add entry to database</guibutton>). +In this case you should specify the author of the new translation in <guilabel>Auto added +entry author</guilabel>. +</para> +<para> +The rest of the tab allows you to fill the database from PO files that already exist. Use one +of the buttons in the middle of the dialog box. The progress of the file load will be +shown by progress bars below the buttons. The <guilabel>Repeated strings</guilabel> +button should be used in the special case where one translated string is repeated many +times, to prevent storing unnecessary copies. Here you can limit the stored strings. +</para> +<screenshot> +<screeninfo>Filling the database</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dbcan.png" format="PNG"/> +</imageobject> +<textobject><phrase>Filling the database by existing PO-files</phrase></textobject> +</mediaobject> +</screenshot></sect2> + +<sect2 id="database-goodkeys"> +<title>Defining good keys</title> +<para> +On the <guilabel>Good keys</guilabel> tab are the thresholds to specify how to fill +the list of good keys. +<guilabel>Minimum number of query words in the key (%)</guilabel> specifies exactly that. +Text will need to contain only this per cent of the words to qualify as good key. Opposite can +be specified via <guilabel>Minimum number of words of the key also in the query (%)</guilabel>. +The length of the words can be set by <guilabel>Max length</guilabel> spinbox. +</para> +<para>Searched text typically contains number of generic words, ⪚ articles. You can +eliminate the words based on the frequency. You can discard them by +<guilabel>Discard words more frequent than</guilabel> or consider as always present by +<guilabel>frequent words are considered as in every key</guilabel>. This way the +frequent words will be almost invisible for queries. +</para> +</sect2> +</sect1> + + +<sect1 id="auxiliary"> +<title>Auxiliary PO file</title> + +<para>This searching mode is based on matching the same original +English string (the msgid) translated in some other language in an +auxillary <acronym>PO</acronym> file. It is very common for Romance +<!-- ### TODO: is "Anglo-Saxon" not too Romance or too technical for an English text? --> +languages to have similar words, similarly for Anglo-Saxon and +Slavic ones.</para> + +<para> +For example, say I wanted to translate the word +<quote>on</quote>, from <filename>kdelibs.po</filename>, into Romanian +but have no clue. I look in the same file for French and find +<foreignphrase lang="fr">actif</foreignphrase>, and in the Spanish one find +<foreignphrase lang="es">activado</foreignphrase>. So, I conclude that the best one in Romanian +will be <foreignphrase lang="ro">active</foreignphrase>. +(Of course, in English instead of <quote>on</quote> the word could have been +<quote>active</quote> or <quote>activated</quote>, +which would have made the translation process easier.) +&kbabel; automates this task. Currently you can define only one auxiliary file to search. +</para> + +<sect2 id="auxiliary-settings"> +<title>Settings</title> +<para> +You can configure this searching mode by selecting +<menuchoice> + <guisubmenu>Settings</guisubmenu> + <guisubmenu>Configure Dictionary</guisubmenu> + <guimenuitem>PO Auxiliary</guimenuitem> +</menuchoice> +from the &kbabel; menu.</para> + +<para>In the <guilabel>Configure Dictionary PO Auxiliary</guilabel> +dialog you can select the path to the auxiliary <acronym>PO</acronym> +file. To automate <acronym>PO</acronym>-file switching when you +change current edited file there are many variables delimited by +<literal>@</literal> char that are replaced by appropriate +values:</para> + +<variablelist> + <varlistentry> + <term>@PACKAGE@</term> + <listitem><para> + The name of application or package currently being translated. + For example, it can expand to kbabel, kdelibs, konqueror + and so on. + </para></listitem> + </varlistentry> + <varlistentry> + <term>@LANG@</term> + <listitem><para> + The language code. + For example can expand to: de, ro, fr etc. + </para></listitem> + </varlistentry> + <varlistentry> + <term>@DIRn@</term> + <listitem><para> + where <quote>n</quote> is a positive integer. This expands to + the <quote>n</quote>-th folder counted from the filename (right to + left). + </para></listitem> + </varlistentry> +</variablelist> + +<para>The edit line displays the actual path to the auxiliary +<acronym>PO</acronym> file. While it is best to use the +provided variables in a path it is possible to choose an absolute, +real path to an existing <acronym>PO</acronym> file. Let's take an +example.</para> + +<para>I'm Romanian and I have some knowledge about French language and +I work on &kde; translation.</para> + +<!-- ### TODO: check URL, especially the kde-l10n part --> +<para>First step is to download a very fresh +<filename>kde-l10n-fr.tar.bz2</filename> from the <ulink +url="ftp://ftp.kde.org/pub/kde/snapshots/kde-l10n">&kde; &FTP; +site</ulink> or to use the <acronym>CVS</acronym> system to put on my +hard-disk a French translation tree. I do this into +<filename>/home/clau/cvs-cvs.kde.org/kde-l10n/fr</filename>.</para> + +<para>My <acronym>PO</acronym> sources folder is in +<filename>/home/clau/cvs-cvs.kde.org/kde-l10n/ro</filename>. Do not +forget to select <guilabel>PO Auxiliary</guilabel> as the default +dictionary and check <guilabel>Automatically start search</guilabel> +on the <guilabel>Search</guilabel> tab from &kbabel;'s +<guilabel>Preferences</guilabel> dialog.</para> + +</sect2> +</sect1> + +<sect1 id="compendium"> +<!-- FIXME: examples --> +<title>PO compendium</title> + +<para>A compendium is a file containing a collection of all +translation messages (pairs of <acronym>msgid</acronym> and +<acronym>msgstr</acronym>) in a project, ⪚ in &kde;. Typically, +compendium for a given language is created by concatenating all +<acronym>PO</acronym> files of the project for the +language. Compendium can contain translated, untranslated and fuzzy +messages. Untranslated ones are ignored by this module. </para> + +<para>Similarly to Auxiliary <acronym>PO</acronym>, this searching +mode is based on matching the <quote>same</quote> original string +(<acronym>msgid</acronym>) in a compendium. Currently you can define +only one compendium file to search. </para> + +<para>This mode is very useful if you are not using the translation +database and you want to achieve consistent translation with other +translations. By the way, compendium files are much easier to share +with other translators and even other translation projects because +they can be generated for them as well. </para> + +<sect2 id="compendium-settings"> +<title>Settings</title> + +<para> +You can configure this searching mode by selecting +<menuchoice> + <guisubmenu>Settings</guisubmenu> + <guisubmenu>Configure Dictionary</guisubmenu> + <guimenuitem>PO Compendium</guimenuitem> +</menuchoice> +in &kbabel;'s menu. +</para> + +<para>In <guilabel>Configure Dictionary PO Compendium</guilabel> +dialog you can select the path to a compendium file. To automate +compendium file switching when you change the translation language, +there is a variable delimited by <literal>@</literal> char which si +replaced by appropriate value:</para> + +<variablelist> + <varlistentry> + <term>@LANG@</term> + <listitem><para> + The language code. + For example can expand to: de, ro, fr etc. + </para></listitem> + </varlistentry> +</variablelist> + +<para>In the edit line is displayed the actual path to compendium +<acronym>PO</acronym> file. While you had best use provided variables in +path, it's possible to choose an absolute, real path to an existing +<acronym>PO</acronym> file to be used as a compendium.</para> + +<!-- ### TODO: check URL, especially the kde-l10n part --> +<para>A very fresh compendium for &kde; translation into ⪚ French +you can download <filename>fr.messages.bz2</filename> from the <ulink +url="ftp://ftp.kde.org/pub/kde/snapshots/kde-l10n">&kde; &FTP; +site</ulink>. </para> + +<para>You can define how to search in the compendium using options +below the path. They are divided into two groups: text-matching +options, where you can specify how the text is compared and whether to +ignore fuzzy translations, and message-matching options, which +determine if the translation from compendium should be a substring of +searching message or vice versa.</para> + +<variablelist> + <varlistentry> + <term><guilabel>Case sensitive</guilabel></term> + <listitem> + <para> + If the matching of message in compendium should distinguish between uppercase and lowercase letters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Ignore fuzzy string</guilabel></term> + <listitem> + <para> + If the fuzzy messages in the compendium should be ignored for searching. The compendium can contain fuzzy messages, since it is typically created by concatenating the <acronym>PO</acronym> files of the project which can include fuzzy messages. Untranslated ones are ignored always (You can't search for translation in untranslated messages, right?)</para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Only whole words</guilabel></term> + <listitem> + <para> + If the matching text should start and end at the boundaries of words. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>is equal to search text</guilabel></term> + <listitem> + <para> + A text in compendium matches the search text only if it is exactly the same (of course using the options above). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>is similar to search text</guilabel></term> + <listitem> + <para> + A text in compendium matches the search text only if it is <quote>similar</quote>. Both texts are compared by short chunks of letters (<quote>3-grams</quote>) and at least half of the chunks has to be same. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>contains search text</guilabel></term> + <listitem> + <para> + A text in compendium matches the search text if it contains the search text.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>is contained in search text</guilabel></term> + <listitem> + <para> + A text in compendium matches the search text if it is contained the search text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>contains a word of search text</guilabel></term> + <listitem> + <para> + The texts are divided to words and a text in compendium matches the search text only if it contains some word from the search text. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> +</sect1> +</chapter> +<!-- +Local Variables: +mode: xml +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/kbabel/editcopy.png b/doc/kbabel/editcopy.png Binary files differnew file mode 100644 index 00000000..c600e997 --- /dev/null +++ b/doc/kbabel/editcopy.png diff --git a/doc/kbabel/editcut.png b/doc/kbabel/editcut.png Binary files differnew file mode 100644 index 00000000..21c36739 --- /dev/null +++ b/doc/kbabel/editcut.png diff --git a/doc/kbabel/editpaste.png b/doc/kbabel/editpaste.png Binary files differnew file mode 100644 index 00000000..f6a1db8f --- /dev/null +++ b/doc/kbabel/editpaste.png diff --git a/doc/kbabel/faq.docbook b/doc/kbabel/faq.docbook new file mode 100644 index 00000000..ce8a6737 --- /dev/null +++ b/doc/kbabel/faq.docbook @@ -0,0 +1,66 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> --> +<!-- Uncomment the previous two lines to validate this document --> +<!-- standalone. Be sure to recomment them before attempting to --> +<!-- process index.docbook --> + +<chapter id="faq"> +<chapterinfo> +<!-- Fill in this section if this document has a different author --> +<authorgroup> +<author> +<personname><firstname></firstname><surname></surname></personname> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</chapterinfo> + +<title>Questions and Answers</title> +<qandaset> + <!-- ### FIXME: describe better the situation of Qt3. (This text sounds like being for Qt2.) --> + <qandaentry> + <question> + <para> + Why does &kbabel; show question marks instead of language specific +characters after loading a <acronym>PO</acronym> file?</para> + </question> + <answer> + <para> + The text contains characters, which can not be displayed with your system font. If you are sure, that the text contains no such characters, the file might have been corrupted somehow. In this case, mark such a question mark and press + <keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo> to find all the corrupted characters and replace them.<note> + <para> + Do not search for real question marks, because these characters are only displayed as question marks, but internally they are different characters. + </para> + </note> + Otherwise you might want to install an Unicode font, which contains all + necessary characters. + </para> + </answer> + </qandaentry> +<qandaentry> +<question> +<para> +How can I translate &kde;? +</para> +</question> +<answer> +<para> +You can look for information about how to translate KDE in the +<ulink url="http://i18n.kde.org/translation-howto/">The KDE Translation HOWTO</ulink>. +</para> +</answer> +</qandaentry> +</qandaset> +</chapter> +<!-- +Local Variables: +mode: xml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +vim:tabstop=2:shiftwidth=2:expandtab +-->
\ No newline at end of file diff --git a/doc/kbabel/fileopen.png b/doc/kbabel/fileopen.png Binary files differnew file mode 100644 index 00000000..2d27efc8 --- /dev/null +++ b/doc/kbabel/fileopen.png diff --git a/doc/kbabel/filesave.png b/doc/kbabel/filesave.png Binary files differnew file mode 100644 index 00000000..14d339d8 --- /dev/null +++ b/doc/kbabel/filesave.png diff --git a/doc/kbabel/find.png b/doc/kbabel/find.png Binary files differnew file mode 100644 index 00000000..92ae8f30 --- /dev/null +++ b/doc/kbabel/find.png diff --git a/doc/kbabel/forward.png b/doc/kbabel/forward.png Binary files differnew file mode 100644 index 00000000..66315588 --- /dev/null +++ b/doc/kbabel/forward.png diff --git a/doc/kbabel/glossary.docbook b/doc/kbabel/glossary.docbook new file mode 100644 index 00000000..8138da5b --- /dev/null +++ b/doc/kbabel/glossary.docbook @@ -0,0 +1,211 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE glossary PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> --> +<!-- Uncomment the previous two lines to validate this document --> +<!-- standalone. Be sure to recomment them before attempting to --> +<!-- process index.docbook --> + +<glossary id="glossary"> +<glossaryinfo> +<!-- Fill in this section if this document has a different author --> +<authorgroup> +<author> +<personname><firstname></firstname><surname></surname></personname> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</glossaryinfo> + +<title>Glossary</title> + +<glossdiv><title>A</title> + <glossentry id="gloss-auxiliary"> + <glossterm>Auxiliary file</glossterm> + <glossdef> + <para> + is a &kbabel; specific issue. It is an option for the user to + set up one <acronym>PO</acronym> file to search through for original messages. For example, + if you're a member of French team and have some Spanish or Italian + knowledge you can grab and set-up an auxiliary Spanish <acronym>PO</acronym> file + associated with the file currently being translated. + + </para> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>C</title> + <glossentry id="gloss-compendium"> + <glossterm>Compendium file</glossterm> + <glossdef> + <para> + is a collection of all translations + for one language. This big <acronym>PO</acronym> file + is made by unique messages from all + applications' <acronym>PO</acronym> files. It can + be used to fill in all already translated + strings into a new yet untranslated + or partially translated <acronym>PO</acronym> file. + &kbabel; uses such a file in the <quote>PO Compendium</quote> + search engine. + </para> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>F</title> + <glossentry id="fuzzy"> + <glossterm>Fuzzy</glossterm> + <glossdef> + <para> + This is a flag generated, in general, + by <command>msgmerge</command>. It shows + that a <acronym>msgstr</acronym> string + might not be a correct translation. + The translator must see and make modifications + to the string if necessary and then remove + the <quote>fuzzy</quote> flag + from the message's comment. + </para> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>I</title> + <glossentry id="i18n"> + <glossterm>Internationalization</glossterm> + <acronym>i18n</acronym> + <glossdef> + <para> + is the operation by which an application + is made aware and able to support multiple + languages. The word <quote>internationalization</quote> + has 20 characters so, to shorten it, + people started to write only + the first and last characters and between them + write the number of intermediate characters (18) + forming the common abbreviation <acronym>i18n</acronym>. + </para> + <glossseealso otherterm="l10n"></glossseealso> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>L</title> + <glossentry id="l10n"> + <glossterm>Localization</glossterm> + <acronym>l10n</acronym> + <glossdef> + <para> + is the operation by which an application + already internationalized is made + to process input and output in a fashion + desired by some cultural and language habits. + The word <quote>localization</quote> + has 12 characters so, to shorten it, + people started to write only + the first and last characters and between them + write the number of intermediate characters (10) + forming the common abbreviation <acronym>l10n</acronym>. + </para> + <glossseealso otherterm="i18n"></glossseealso> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>M</title> + <glossentry id="mofile"> + <glossterm>MO file</glossterm> + <acronym>MO</acronym> + <glossdef> + <para> + <acronym>MO</acronym> stands for <quote>Machine Object</quote>. A <acronym>MO</acronym> file + contains binary data suitable + for reading by computers. + The contents of a <acronym>MO</acronym> file are organized as a database + to minimize the lookup time + for translated strings. <acronym>MO</acronym> files + are obtained by compiling <acronym>PO</acronym> files + using <command>msgfmt</command>. + + </para> + <glossseealso otherterm="pofile"></glossseealso> + <glossseealso otherterm="potfile"></glossseealso> + </glossdef> + </glossentry> + <glossentry id="msgid"> + <glossterm>Message ID</glossterm> + <acronym>msgid</acronym> + <glossdef> + <para> + <acronym>msgid</acronym> is the keyword + which introduces the original string in a <acronym>PO</acronym> file. + It is followed by a C-like string that spans + one or more lines. + </para> + <glossseealso otherterm="msgstr"></glossseealso> + </glossdef> + </glossentry> + <glossentry id="msgstr"> + <glossterm>Message String</glossterm> + <acronym>msgstr</acronym> + <glossdef> + <para> + <acronym>msgstr</acronym> is the keyword + which introduce the translated string in <acronym>PO</acronym> file. + It is followed by C-like string that span + on one or multiple lines. + </para> + <glossseealso otherterm="msgid"></glossseealso> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>P</title> + <glossentry id="pofile"> + <glossterm>PO file</glossterm> + <acronym>PO</acronym> + <glossdef> + <para> + <acronym>PO</acronym> stands for <quote>Portable Object</quote>. <acronym>PO</acronym> files + contain sets of strings which + associate each translatable string + with its translation in a particular + language. A single <acronym>PO</acronym> file relates + to only one language. A <acronym>PO</acronym> file is + derived from a <acronym>POT</acronym> file and is + edited either by hand or using &kbabel;. + </para> + <glossseealso otherterm="potfile"></glossseealso> + <glossseealso otherterm="mofile"></glossseealso> + </glossdef> + </glossentry> + <glossentry id="potfile"> + <glossterm>POT file</glossterm> + <acronym>POT</acronym> + <glossdef> + <para> + <acronym>POT</acronym> stands for <quote>Portable Object Template</quote>. A <quote>POT</quote> file is built by extracting all the + translatable strings from application + source files. A <quote>POT</quote> file does not + contain translations into any particular language— + it is used by the translators as a template. + </para> + <glossseealso otherterm="pofile"></glossseealso> + <glossseealso otherterm="mofile"></glossseealso> + </glossdef> + </glossentry> +</glossdiv> + +</glossary> +<!-- +Local Variables: +mode: xml +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/kbabel/index.docbook b/doc/kbabel/index.docbook new file mode 100644 index 00000000..51cb8661 --- /dev/null +++ b/doc/kbabel/index.docbook @@ -0,0 +1,174 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY using SYSTEM "using.docbook"> + <!ENTITY kbabeldictchapter SYSTEM "kbabeldict.docbook"> + <!ENTITY catman SYSTEM "catman.docbook"> + <!ENTITY dictionaries SYSTEM "dictionaries.docbook"> + <!ENTITY menu SYSTEM "menu.docbook"> + <!ENTITY preferences SYSTEM "preferences.docbook"> + <!ENTITY kbabelfaq SYSTEM "faq.docbook"> + <!ENTITY glossary SYSTEM "glossary.docbook"> + <!ENTITY kappname "&kbabel;"> + <!ENTITY package "kdesdk"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kbabel; Handbook</title> + +<authorgroup> +<author> +&Stanislav.Visnovsky; &Stanislav.Visnovsky.mail; +</author> +<author> +&Matthias.Kiefer; +</author> +<author> +<firstname>Nicolas</firstname> +<surname>Goutte</surname> +<email>goutte@kde.org</email> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + + +<date>2005-12-29</date> +<releaseinfo>3.5.1.03</releaseinfo> + +<abstract> +<para> +&kbabel; is a suite of of an advanced and easy to use +<acronym>PO</acronym> file editor comprising &kbabel;, a multi +functional &catalogmanager; and a dictionary for translators +&kbabeldict;. It supports many advanced features and it lets you +customize many options. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KBabel</keyword> +<keyword>catalogmanager</keyword> +<keyword>kdesdk</keyword> +<keyword>gettext</keyword> +<keyword>translation</keyword> +<keyword>i18n</keyword> +<keyword>internationalization</keyword> +<keyword>l10n</keyword> +<keyword>localization</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<important><para> +In its current state, this KBabel documentation is partially outdated. +The basic documentation was meant for KDE 3.2, +the corrections are meant for KBabel 1.11.1 of KDE 3.5.1. +</para></important> + +<para> +&kbabel; is an advanced and easy to use <acronym>PO</acronym> file +(&GNU; gettext message catalogs) editor. It has many features, that +make it easy to edit and manage your <acronym>PO</acronym> files. +This includes full navigation capabilities, extensive editing +functionality, search functions, syntax checking and statistics +function. &catalogmanager; is a file manager view, which helps you +keep an overview over your <acronym>PO</acronym> files. &kbabeldict; +allows you to translate any text using &kbabel; capabilities for +automated translation. The &kbabel; suite will help you to translate +quickly and also to keep translations consistent. +</para> + +<para> +With the &kde; project growing continuously, the number of +<acronym>PO</acronym> messages is over 47000 at the time of writing +this documentation (plus another 20000 messages used for translating +application documentation). There is a need to stay organized and +consistent across all translations. +</para> + +</chapter> + +&using; +&catman; +&kbabeldictchapter; +&dictionaries; +&preferences; +&menu; +&kbabelfaq; + + +<chapter id="credits"> +<title>Credits and License</title> + +<para> +&kbabel; +</para> +<para> +Program Copyright © 1999-2000 &Matthias.Kiefer; &Matthias.Kiefer.mail; +</para> +<para> +Contributors: +<itemizedlist> +<listitem><para>&Thomas.Diehl; &Thomas.Diehl.mail;</para> +</listitem> +<listitem><para>&Stephan.Kulow; &Stephan.Kulow.mail;</para> +</listitem> +</itemizedlist> +</para> + +<para>Documentation Copyright © 2000 &Claudiu.Costin; +&Claudiu.Costin.mail; and &Matthias.Kiefer; +&Matthias.Kiefer.mail;</para> + +<para>Update for &kde; 3.0 Copyright © 2002 &Stanislav.Visnovsky; +&Stanislav.Visnovsky.mail;</para> + +<para>Update for &kde; 3.5.1 Copyright © 2005 Nicolas Goutte +<email>goutte@kde.org</email></para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> + +&glossary; + +<appendix id="mailing-list"> +<title>Mailing List For KBabel</title> + +<para> +There is a mailing list for KBabel named kbabel. +It is a mixed list for developers and for users of KBabel. +</para> + +<para> +You can subscribe it at +<ulink url="http://mail.kde.org/mailman/listinfo/kbabel/">the Mailman interface</ulink>. +</para> + +<para> +The mailing list has +<ulink url="http://mail.kde.org/pipermail/kbabel/">a public archive</ulink>. +</para> + +</appendix> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +End: +--> diff --git a/doc/kbabel/kbabeldict.docbook b/doc/kbabel/kbabeldict.docbook new file mode 100644 index 00000000..efe70b79 --- /dev/null +++ b/doc/kbabel/kbabeldict.docbook @@ -0,0 +1,85 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> --> +<!-- Uncomment the previous two lines to validate this document --> +<!-- standalone. Be sure to recomment them before attempting to --> +<!-- process index.docbook --> + +<!-- Note: the id attribute "using-kbabeldict" is used in KBabelDict's source code to call the help. +So if you change this id attribute, the name *must* be changed in KBabelDict's source code too! --> +<chapter id="using-kbabeldict"> +<chapterinfo> +<!-- Fill in this section if this document has a different author --> +<authorgroup> +<author> +<personname><firstname></firstname><surname></surname></personname> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</chapterinfo> + +<title>Using &kbabeldict;</title> +<anchor id="kbabeldict"/> +<para> +&kbabeldict; is a simple interface for translation modules for +&kbabel;. It allows you to search for translations. +</para> +<screenshot> +<screeninfo>Screenshot of &kbabeldict;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="snap_kbabeldict.png" format="PNG"/> +</imageobject> +<textobject><phrase>Screenshot of &kbabeldict;</phrase></textobject> +</mediaobject> +</screenshot> +<para> +The screenshot +above does not contain settings for selected module. You can show +them using <guibutton>Show Settings</guibutton>. Preferences +widget for selected module will be shown on the +right side of the window. The &kbabeldict; +window then looks like this: +</para> +<screenshot> +<screeninfo>Screenshot of &kbabeldict;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="snap_kbabeldict2.png" format="PNG"/> +</imageobject> +<textobject><phrase>Screenshot of &kbabeldict; with shown settings</phrase></textobject> +</mediaobject> +</screenshot> +<para> +The usage is very simple. You select a module to in the +<guilabel>Search in module</guilabel> combo-box. +Then you enter the phrase to lookup and press <guibutton>Start +Search</guibutton>. All found messages are shown in the list +below, which is the same as a tool in the &kbabel; main window. +Searching can be stopped by pressing <guilabel>Stop</guilabel>. +In case you want to search in translated text, not in original English message, +you should use <guilabel>Search in translations</guilabel>. +</para> +<para> +Buttons on the bottom of the window can be used for closing &kbabeldict;, +showing/hiding the module settings or displaying a dialog with credits for +&kbabeldict; and the modules themselves. +</para> +<note> +<para> +For description of the standard modules and their settings see +<xref linkend="dictionaries"/>. +</para> +</note> +</chapter> +<!-- +Local Variables: +mode: xml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +vim:tabstop=2:shiftwidth=2:expandtab +-->
\ No newline at end of file diff --git a/doc/kbabel/man-catalogmanager.1.docbook b/doc/kbabel/man-catalogmanager.1.docbook new file mode 100644 index 00000000..00d500c0 --- /dev/null +++ b/doc/kbabel/man-catalogmanager.1.docbook @@ -0,0 +1,77 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<date>2003-03-07</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>catalogmanager</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>catalogmanager</command></refname> +<refpurpose>Advanced catalog manager for &kbabel;</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>catalogmanager</command> +<group><option>--project</option> <replaceable>config-file</replaceable></group> +<group><option>KDE Generic Options</option></group> +<group><option>Qt Generic Options</option></group> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para>CatalogManager is part of a suite of programs for editing +gettext message files (PO-files). This suite is designed to help you +translate fast and consistently.</para> + +<para>This suite includes &kbabel;, +<application>CatalogManager</application> and &kbabeldict;. &kbabel; +is an advanced and easy to use PO-file editor with full navigational +and editing capabilities, syntax checking and +statistics. <application>CatalogManager</application> (this program) +is a multi functional catalog manager which allows you to keep track +of many PO-files at once. &kbabeldict; is a dictionary for +translators.</para> +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>--project</option> <replaceable>config-file</replaceable></term> +<listitem> +<para>Load the configuration from the given file.</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>kbabel(1) kbabeldict(1)</para> + +<para>More detailed user documentation is available from <ulink +url="help:/kbabel">help:/kbabel</ulink> (either enter this +<acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kbabel</parameter></userinput>).</para> + +</refsect1> + +</refentry> diff --git a/doc/kbabel/menu.docbook b/doc/kbabel/menu.docbook new file mode 100644 index 00000000..14c474b5 --- /dev/null +++ b/doc/kbabel/menu.docbook @@ -0,0 +1,2320 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> --> +<!-- Uncomment the previous two lines to validate this document --> +<!-- standalone. Be sure to recomment them before attempting to --> +<!-- process index.docbook --> + +<chapter id="commands"> + +<chapterinfo> +<!-- Fill in this section if this document has a different author --> +<authorgroup> +<author> +<personname><firstname></firstname><surname></surname></personname> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</chapterinfo> + +<title>Command Reference</title> + +<sect1 id="kbabel-menu"> +<title>The &kbabel; menu</title> + +<sect2> +<title>The File Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>O</keycap> + </keycombo> + </shortcut> + <guimenu>File</guimenu> + <guimenuitem>Open</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a PO file. If the current file + is modified you will be prompted to save it first. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Open Recent</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a recently edited PO file from the recently-used documents menu + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>S</keycap> + </keycombo> + </shortcut> + <guimenu>File</guimenu> + <guimenuitem>Save</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Saves the current PO file. If it is not modified no action is taken. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Save As</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Saves the current PO file under a new name + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Save Special</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Displays the Save Settings dialog and then saves the current PO file under a new name + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Revert</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Loads the last saved version of the current PO file + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Mail</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Prompts for an archive filename in which to store the current PO file then opens an email composer + window with the archive as an attachment + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>New View</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a new window with the currently loaded file. + </action> + Very useful if you have to translate large + files and need to refer back to some strings. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>New Window</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a new empty window + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Q</keycap> + </keycombo> + </shortcut> + <guimenu>File</guimenu> + <guimenuitem>Quit</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Quits &kbabel; editor + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Edit Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Z</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Undo</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Undoes the last edit action in the translation edit box + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Shift;<keycap>Z</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Redo</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Redoes the last undone edit action in the translation edit box + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>X</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Cut</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Cuts the selected text and moves it to the clipboard + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>C</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Copy</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Copies the selected text to the clipboard + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>V</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Paste</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Pastes the contents of the clipboard at the current cursor + position in the translation edit box. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Select All</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Selects all text in the translation edit box + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>F</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Find...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a Find dialog for searching for strings in the current PO file + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycap>F3</keycap> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Find Next</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Finds the next occurrence of a string from the previous search action + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>R</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Replace...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens the Replace dialog to search for and replace strings in the current PO file + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Delete</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Clear</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Clears the translation for the current msgid + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Space</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Copy msgid to msgstr</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Copies the original English string into the translation edit + box. This is useful when you do not need to make any changes + (or only minor changes) to the original English text (msgstr). + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Alt;<keycap>Space</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Copy search result to msgstr</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Copies a string found after a translation search + into the msgstr edit box. This is + very useful if you do not want to keep + re-translating the same message again and again. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>U</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Toggle Fuzzy Status</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Toggles the fuzzy status for the current entry.</action> It can be useful to turn fuzzy on, + ⪚ to mark the translation for another review. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Alt;<keycap>N</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Insert Next Tag</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Inserts the next tag found in the msgid into the translation, if the original English string contains markup tags + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul">&Ctrl;&Alt;<keycap>N</keycap></keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guisubmenu>Insert Tag</guisubmenu> + </menuchoice> + </term> + <listitem> + <para> + <action> + This submenu contains all markup tags found in the original English string. By selecting one of them you can insert at the current position of cursor in translated text. + translation. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Edit Header...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Edits the PO file header. + </action> + Actually there are many header lines, which + keep the last translated date, translator name and email, language and + translated text encoding, &etc;. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + + +<sect2> +<title>The Go Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycap>Page Up</keycap> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Skips to the previous entry in the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycap>Page Down</keycap> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Skips to the next entry in the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Go</guimenu> + <guimenuitem>Go to...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a dialog to jump to a specific entry number within the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Go</guimenu> + <guimenuitem>First Entry</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the first entry in the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Go</guimenu> + <guimenuitem>Last Entry</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the last entry in the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Shift;<keycap>Page Up</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous fuzzy or untranslated</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the entry previous to the current one that is untranslated or + marked as fuzzy. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Shift;<keycap>Page Down</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next fuzzy or untranslated</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the next entry after the current one which is untranslated or + marked as fuzzy. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>PgUp</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous fuzzy</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the entry previous to the current one that is marked as fuzzy. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Page Down</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next fuzzy</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the next entry after the current one that is marked as fuzzy. + </action> + </para> + </listitem> + </varlistentry> +<varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Alt;<keycap>Page Up</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous untranslated</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the entry previous to the current one that is untranslated. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Alt;<keycap>Page Down</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next untranslated</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the next entry after the current one that is untranslated. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Shift;<keycap>Page Up</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous error</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the previous entry that has an error. This is usually when + double-quotes are not escaped or the original string ends with a + "newline" (\n) character and the translated string does not (and vice versa). + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Shift;<keycap>Page Down</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next error</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the next entry with an error. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Alt;<keycap>Left Arrow</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Back</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jump to last visited entry</action> in PO file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Alt;<keycap>Right Arrow</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Forward</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jump to previous visited entry</action> in PO file. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + + +<sect2> +<title>The Dictionaries Menu</title> +<para> +Note that this menu is dynamic: it depends on the installed dictionaries plugins. +By default are three of them. +</para> + +<variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Text</guimenuitem> + <guimenuitem>KDE Database Search Engine</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching translation for current original + English message</action> using &kde; Database Search Engine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Text</guimenuitem> + <guimenuitem>PO Auxiliary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching translation for current original + English message</action> in <acronym>PO</acronym> file defined by user. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Text</guimenuitem> + <guimenuitem>PO Compendium</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching translation for current original + English message in compendium file (made + by merging all translated messages for + one language). + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Selected Text</guimenuitem> + <guimenuitem>KDE Database Search Engine</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching selected text</action> + using &kde; Database Search Engine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Selected Text</guimenuitem> + <guimenuitem>PO Auxiliary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching selected text + using file defined by user. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Selected Text</guimenuitem> + <guimenuitem>PO Compendium</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching selected text + using compendium file with + all language translated messages. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Edit Dictionary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Allow you to edit content + of current dictionary. Useful + if you found errors in dictionary + and do not want errors to be reported + when searching and replacing + strings. + </action> + <emphasis>(Not implemented yet)</emphasis> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + + + +<sect2> +<title>The Tools Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Spell check...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Display the spell-check configuration dialog.</action> + After you have chosen the desired options, hit + <guibutton>OK</guibutton> and the normal spell-checking + dialog will appear. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Check All...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start spell-checking all words</action> + for an opened <acronym>PO</acronym> file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Check From Cursor Position...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start spell-checking + from current cursor position. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Check Current...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Spell-check only current</action> + entry from <acronym>PO</acronym> file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Check Marked Text...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Spell-check only + selected text in MsgStr editbox. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>T</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Syntax</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Check syntax</action> for current <acronym>PO</acronym> file. + Errors may appear from <acronym>CVS</acronym> merging + or users' mistakes when the translating + process is performed by hand. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>D</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Arguments</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When this option is selected, C-format strings in the original message and + the translation are checked to ensure the number of + format sequences and the order are consistent. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>H</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Accelerators</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + When this option is selected, &kbabel; <action>checks if the number +of accelerator + characters is identical in both the original and the translated + string.</action> Note that accelerator marker is & in &kde; + (but not in every programming toolkit). See the + <link linkend="preferences-project-miscellaneous">Miscellaneous</link> section + below to find out how to change a keyboard accelerator. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>K</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Look for Translated Context Info</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Some original messages are marked with + context information to mark them as being unique even + if they represent same word. This is because + many simple words, such as <quote>Save</quote>, are translated into + many languages. Context information + is marked with <literal>_:</literal>. Many + unexperienced translators translate the context information + and fill their <quote>PO</quote> files with garbage. <action>Check this box to make sure you will be warned about these errors in a file.</action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Plural Forms (KDE only)</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Check if the <acronym>PO</acronym> file <action>contains the correct number of translations</action> for each &kde;-specific plural form message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>J</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Equations</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Check whether the left side of the translated string + is the same as the left side of the original string. + Sides are delimited by an equals-sign character. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo> + <keycap>F5</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Diff</guimenuitem> + <guimenuitem>Show Diff</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Show difference found to the original translated message. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo> + <keycap>F6</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Diff</guimenuitem> + <guimenuitem>Show Original Text</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Hide difference markings and show msgid only. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Diff</guimenuitem> + <guimenuitem>Open File for Diff</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open file to be used for difference lookup. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Diff</guimenuitem> + <guimenuitem>Diffmode</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Toggle difference mode. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Rough Translation...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Invoke rough-translation dialog for automated translation. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Catalog Manager...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open &catalogmanager;. Read + <link linkend="using-catalogmanager">&catalogmanager;</link> section + for more details. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Settings Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Toolbar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the standard toolbar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Statusbar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the bottom statusbar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Navigation Bar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the navigation bar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Comments</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the upper-right part of main window, + which contains current entry's comments, will be displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Tools</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the bottom-right part of main window, + which contain search results through the + dictionary, will be displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Key Bindings...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a configure dialog for binding keys to + actions. This will let you to customize the default + key bindings to suite your needs. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Toolbars...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Standard toolbar-configuration dialog will open. You can + choose which actions will go in which toolbars and what toolbar + to customize. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Kbabel...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + All &kbabel;-specific settings go here. + Please read the <link linkend="preferences-global">&kbabel; Global Settings</link> section for specific topics. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Dictionary</guimenuitem> + <guimenuitem>KDE Database Search Engine</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open dialog for &kde; Database Search Engine + configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Dictionary</guimenuitem> + <guimenuitem>PO Auxiliary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open dialog</action> for <acronym>PO</acronym> auxiliary file + configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Dictionary</guimenuitem> + <guimenuitem>PO Compendium</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open dialog</action> for <acronym>PO</acronym> compendium file + configuration. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Help Menu</title> + +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycap>F1</keycap> + </shortcut> + <guimenu>Help</guimenu> + <guimenuitem>Contents</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open the &kbabel; handbook. It is what + you are reading now. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo> + &Shift;<keycap>F1</keycap> + </keycombo> + </shortcut> + <guimenu>Help</guimenu> + <guimenuitem>What's This?</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Cursor change to arrow with question mark and you can click with it + on various elements on main window. A quick help window will open. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>Gettext Info</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open the gettext manual page</action> in the &kde; Help Center. + This package of tools helps the in process of handling + <acronym>POT</acronym> and <acronym>PO</acronym> files. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>Report Bug...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + This will open a standard error-reporting dialog + </action> for &kde; + It is useful if + you experience abnormal behavior of &kbabel;. + &kbabel;'s developer will be glad to receive any comments, wishes, and + bug reports. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About KBabel...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open a message box which inform you about &kbabel;'s version, developer + name, and e-mail address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About KDE...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open a message box which informs you about the &kde; project, + contact information, and how you can report bugs and + wishes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About Dictionary</guimenuitem> + <guimenuitem>KDE Database Search Engine</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Display a message box with information + about the people who made the &kde; Database Search Engine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About Dictionary</guimenuitem> + <guimenuitem>PO Auxiliary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Display a message box with information + about the people who made searching in auxiliary file possible. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About Dictionary</guimenuitem> + <guimenuitem>PO Compendium</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Display a message box with information + about people who made searching in compendium file possible. + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> +</sect1> + +<sect1 id="kbabel-toolbars"> +<title>The &kbabel; toolbars</title> + +<sect2 id="standard-toolbar"> +<title>Standard Toolbar</title> +<variablelist> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="fileopen.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Open + </term> + <listitem> + <para>Load <acronym>PO</acronym> file in &kbabel; for editing.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="filesave.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Save + </term> + <listitem> + <para>Save current <acronym>PO</acronym> file if it is modified.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="undo.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Undo + </term> + <listitem> + <para>Undo last operation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="redo.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Redo + </term> + <listitem> + <para>Redo last operation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="editcut.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Cut + </term> + <listitem> + <para>Cut selected text and move it to the clipboard.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="editcopy.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Copy + </term> + <listitem> + <para>Copy selected text to the clipboard.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="editpaste.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Paste + </term> + <listitem> + <para>Paste text from clipboard at the current cursor position.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="find.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Find + </term> + <listitem> + <para>Find specified string in current PO-file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="previous.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous + </term> + <listitem> + <para>Skip to previous entry in PO-file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="next.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next + </term> + <listitem> + <para>Skip to next entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="msgid2msgstr.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Copy <acronym>msgid</acronym> to <acronym>msgstr</acronym> + </term> + <listitem> + <para>Copy original string to translated string edit box.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="transsearch.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Search Translations + </term> + <listitem> + <para>Drop-down toolbar for searching selected text using: + &kde; Database Search Engine, <acronym>PO</acronym> auxiliary file, <acronym>PO</acronym> compendium file, + and other dictionary plugins if available.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="stop.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Stop + </term> + <listitem> + <para>Stop current search-in-progress.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Catalog Manager + </term> + <listitem> + <para>Open Catalog Manager window.</para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="navigation-toolbar"> +<title>Navigation Toolbar</title> +<variablelist> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="previous.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous + </term> + <listitem> + <para>Skip to previous entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="next.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next + </term> + <listitem> + <para>Skip to next entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="top.png" format="PNG"/> +</imageobject> +</inlinemediaobject> First Entry + </term> + <listitem> + <para>Jump to first entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="bottom.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Last Entry + </term> + <listitem> + <para>Jump to last entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="prevfuzzyuntrans.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous fuzzy or untranslated + </term> + <listitem> + <para>Jump to previous fuzzy or untranslated entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="nextfuzzyuntrans.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next fuzzy or untranslated + </term> + <listitem> + <para>Jump to next fuzzy or untranslated entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="prevfuzzy.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous fuzzy + </term> + <listitem> + <para>Jump to previous fuzzy entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="nextfuzzy.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next fuzzy + </term> + <listitem> + <para>Jump to next fuzzy entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="prevuntranslated.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous untranslated + </term> + <listitem> + <para>Jump to previous untranslated entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="nextuntranslated.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next untranslated + </term> + <listitem> + <para>Jump to next untranslated entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="preverror.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous error + </term> + <listitem> + <para>Jump to previous error in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="nexterror.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next error + </term> + <listitem> + <para>Jump to next error in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="back.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Back + </term> + <listitem> + <para>Jump to last visited entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="forward.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Forward + </term> + <listitem> + <para>Jump to previous visited entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="status-bar"> +<title>Status Bar</title> +<variablelist> + <varlistentry> + <term>Current</term> + <listitem> + <para>Current message in edited <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Total</term> + <listitem> + <para>Total number of messages in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Fuzzy</term> + <listitem> + <para>Number of messages marked as fuzzy. They should be revised + and translated if needed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Untranslated</term> + <listitem> + <para>Number of yet untranslated messages.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Editor status</term> + <listitem> + <para>INS - insert, and OVR - overwrite. + Same meaning like in every ordinary text editor. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PO-file status</term> + <listitem> + <para>RO - read-only file, RW - read-write access on file. + When a file is read-only you cannot modify entries + in editor. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Progress bar</term> + <listitem> + <para> + Usually, this bar is hidden; it is displayed + only when saving is being done, or if you are searching for messages + in a PO-file, compendium, or elsewhere. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +</sect1> + +<sect1 id="catalogmanager-menu"> +<title>The &catalogmanager; menu</title> + +<sect2> +<title>The File Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Q</keycap> + </keycombo> + </shortcut> + <guimenu>File</guimenu> + <guimenuitem>Quit</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Quits &catalogmanager;</action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Edit Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>F</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Find in Files...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open Find dialog for searching for strings in a set of PO files. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>R</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Replace in Files...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open Replace dialog for searching for and replacing strings in a set of PO files. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo> + <keycap>Escape</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Stop Searching</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Stop currently running find/replace operation. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>M</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Toggle Marking</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Toggle mark for the selected file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Remove Marking</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Removes mark for the selected file or folder. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Toggle All Markings</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Toggles marks for the selected file or folder (recursively). + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Remove All Markings</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Remove marks for the selected file or folder (recursively). + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Tools Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>S</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Statistics</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Show statistics about number of translated/untranslated/fuzzy messages + for the selected file or subtree. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Y</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Check Syntax</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Check syntax for the selected file or subtree using msgfmt. + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Settings Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Toolbar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, standard toolbar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Statusbar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, bottom statusbar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Key Bindings...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a configure dialog for binding keys to + actions. This will let you to customize the default + key bindings to suite your needs. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Toolbars...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Standard toolbar-configuration dialog will open. You can + choose which actions will go in which toolbars and what toolbar + to customize. + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Help Menu</title> +&help.menu.documentation; +</sect2> + +</sect1></chapter> +<!-- +Local Variables: +mode: xml +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/kbabel/msgid2msgstr.png b/doc/kbabel/msgid2msgstr.png Binary files differnew file mode 100644 index 00000000..938ea3ce --- /dev/null +++ b/doc/kbabel/msgid2msgstr.png diff --git a/doc/kbabel/next.png b/doc/kbabel/next.png Binary files differnew file mode 100644 index 00000000..f0b977bf --- /dev/null +++ b/doc/kbabel/next.png diff --git a/doc/kbabel/nexterror.png b/doc/kbabel/nexterror.png Binary files differnew file mode 100644 index 00000000..1009eae0 --- /dev/null +++ b/doc/kbabel/nexterror.png diff --git a/doc/kbabel/nextfuzzy.png b/doc/kbabel/nextfuzzy.png Binary files differnew file mode 100644 index 00000000..5912e52d --- /dev/null +++ b/doc/kbabel/nextfuzzy.png diff --git a/doc/kbabel/nextfuzzyuntrans.png b/doc/kbabel/nextfuzzyuntrans.png Binary files differnew file mode 100644 index 00000000..fd373e2f --- /dev/null +++ b/doc/kbabel/nextfuzzyuntrans.png diff --git a/doc/kbabel/nextuntranslated.png b/doc/kbabel/nextuntranslated.png Binary files differnew file mode 100644 index 00000000..3b4f8202 --- /dev/null +++ b/doc/kbabel/nextuntranslated.png diff --git a/doc/kbabel/pref_diff.png b/doc/kbabel/pref_diff.png Binary files differnew file mode 100644 index 00000000..014ea5ef --- /dev/null +++ b/doc/kbabel/pref_diff.png diff --git a/doc/kbabel/pref_edit_appearance.png b/doc/kbabel/pref_edit_appearance.png Binary files differnew file mode 100644 index 00000000..1306704e --- /dev/null +++ b/doc/kbabel/pref_edit_appearance.png diff --git a/doc/kbabel/pref_edit_general.png b/doc/kbabel/pref_edit_general.png Binary files differnew file mode 100644 index 00000000..d1542289 --- /dev/null +++ b/doc/kbabel/pref_edit_general.png diff --git a/doc/kbabel/pref_fonts.png b/doc/kbabel/pref_fonts.png Binary files differnew file mode 100644 index 00000000..b92e1b7a --- /dev/null +++ b/doc/kbabel/pref_fonts.png diff --git a/doc/kbabel/pref_proj_catman.png b/doc/kbabel/pref_proj_catman.png Binary files differnew file mode 100644 index 00000000..1e30bb25 --- /dev/null +++ b/doc/kbabel/pref_proj_catman.png diff --git a/doc/kbabel/pref_proj_diff.png b/doc/kbabel/pref_proj_diff.png Binary files differnew file mode 100644 index 00000000..27cb370e --- /dev/null +++ b/doc/kbabel/pref_proj_diff.png diff --git a/doc/kbabel/pref_proj_file_commands.png b/doc/kbabel/pref_proj_file_commands.png Binary files differnew file mode 100644 index 00000000..fe83050f --- /dev/null +++ b/doc/kbabel/pref_proj_file_commands.png diff --git a/doc/kbabel/pref_proj_folder_commands.png b/doc/kbabel/pref_proj_folder_commands.png Binary files differnew file mode 100644 index 00000000..cf0f742f --- /dev/null +++ b/doc/kbabel/pref_proj_folder_commands.png diff --git a/doc/kbabel/pref_proj_source.png b/doc/kbabel/pref_proj_source.png Binary files differnew file mode 100644 index 00000000..278e2ebd --- /dev/null +++ b/doc/kbabel/pref_proj_source.png diff --git a/doc/kbabel/pref_search.png b/doc/kbabel/pref_search.png Binary files differnew file mode 100644 index 00000000..cdb5c6d1 --- /dev/null +++ b/doc/kbabel/pref_search.png diff --git a/doc/kbabel/pref_wizard_page1.png b/doc/kbabel/pref_wizard_page1.png Binary files differnew file mode 100644 index 00000000..b88b954d --- /dev/null +++ b/doc/kbabel/pref_wizard_page1.png diff --git a/doc/kbabel/pref_wizard_page2.png b/doc/kbabel/pref_wizard_page2.png Binary files differnew file mode 100644 index 00000000..e561cff2 --- /dev/null +++ b/doc/kbabel/pref_wizard_page2.png diff --git a/doc/kbabel/preferences.docbook b/doc/kbabel/preferences.docbook new file mode 100644 index 00000000..fbaeee10 --- /dev/null +++ b/doc/kbabel/preferences.docbook @@ -0,0 +1,1418 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> --> +<!-- Uncomment the previous two lines to validate this document --> +<!-- standalone. Be sure to recomment them before attempting to --> +<!-- process index.docbook --> + + +<chapter id="preferences"> +<chapterinfo> +<!-- Fill in this section if this document has a different author --> +<authorgroup> +<author> +<personname><firstname></firstname><surname></surname></personname> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</chapterinfo> + +<title>Preferences</title> + + +<sect1 id="preferences-overview"> +<title>Global and project settings</title> + +<para> +From KBabel 1.10 (KDE 3.4) on, KBabel has the concept of projects and therefore +the settings have been split in two categories: +the global settings and the project settings (also called project configuration). +</para> + +<important><para> +&GNU; gettext uses a term called "project", which has nothing to do with +KBabel's projects. &GNU; gettext means by project an application which is +related to the <acronym>PO</acronym> file. For KBabel, a project is +much bigger. It can mean a set of applications, like &kde;. +</para></important> + +<para> +KBabel has <emphasis>always</emphasis> a current project, even if it is the +default project. KBabel has not mode without any project. A project is always +for KBabel's editor and KBabel's catalog manager. +</para> + + +<sect2 id="preferences-limitations"> +<title>Known limitations of the current implementation</title> + +<para> +Unfortunately the current implementation of projects has a few known problems. +</para> + +<para> +An example is that in the global settings, there is no setting for the default user, +his/her default language and other similar important global user data. It means that such +data must be entered again each time that a new project is created. +</para> + +<para> +Another problem is the new project wizard. It does not ask enough information, especially +it fails to ask for the team email address. So it is recommended to check the project +settings after having run the wizard. +</para> + +<tip><para> +Currently you cannot copy projects from inside KBabel, so apparently you cannot easily share good settings. +However you are free to copy the project outside KBabel and to load the copied project into KBabel. +</para></tip> + +</sect2> + +<sect2 id="preferences-non-kde-projects"> +<title>Using KBabel for non-&kde; projects</title> + +<para> +While &kbabel;'s defaults are oriented toward working with and for &kde;, &kbabel; can be used +to translate <acronym>PO</acronym> files of other projects. However mostly you will have to tweak the +settings to the need of your project. This is especially true for &GNU; and +&GNU;-like projects, which need quite different defaults than for &kde;. +</para> + +<para> +One problem is that &kbabel; is relatively agressive when saving <acronym>PO</acronym> files and +replaces setting of the <acronym>PO</acronym> files by settings of the projects, if not told otherwise. +This might look very strange to somebody not used to &kde;. However &kde; has 900+ +<acronym>POT</acronym> files to translate for the <acronym>GUI</acronym> messages only. +So for such a task, much automatisation is wanted. Taking time to set a project +is little compared to the time gained thereafter. Of course, as non-&kde; user, you +might be less fortunate. You need to do more settings, as the defaults are not entirely suitable +and you will not gain much by doing many translations, as &GNU; projects have typically +only one <acronym>POT</acronym> file to translate. +</para> + +</sect2> + +</sect1> + +<sect1 id="preferences-global"> +<title>&kbabel; global settings</title> + +<para> +To show the Preferences dialog choose +<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure +KBabel...</guimenuitem></menuchoice> from &kbabel;'s menu. It uses a +structured configuration dialog which makes it very easy to find an +option without having to perform an extensive search for it. +</para> + +<sect2 id="preferences-editor"> +<title>Edit</title> +<para> +The editor preferences category is divided in 3 subwindows: +<guilabel>General</guilabel>, <guilabel>Appearance</guilabel>, +<guilabel>Spell Check</guilabel> and <guilabel>Fonts</guilabel>. +All these settings customize how the editor behaves and looks. +</para> + +<sect3 id="preferences-editor-general"> +<title>General</title> + +<screenshot> +<screeninfo>Dialog Edit General</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_edit_general.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Edit General</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This section contains a set of checkboxes.</para> + +<para>The first checkbox in the upper side sets if the fuzzy status is +reset automatically when a character is inputted into the MsgStr +editor. When this option is disabled you have to manually choose +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Unset Fuzzy Status +</guimenuitem></menuchoice> or use the <keycombo +action="simul">&Ctrl;<keycap>U</keycap></keycombo> shortcut. Note +that this means the string <literal>, fuzzy</literal> is removed from +the entry's comment.</para> + +<para>Next option allows you to enable <quote>clever</quote> editing, +where editor automatically inserts special characters escaped +correctly, ⪚ <literal>\t</literal> after pressing +<keycap>Tab</keycap> and it allows special handling of +<keycap>Enter</keycap>.</para> + +<para> +The lower checkboxes are very useful in assisting, not for the +correctness of the translation, but if the translated string +is a suitable replacement for the original. For +example, many messages represent menu items with keyboard accelerator +and C-like formatted strings whose structure must remain intact once +translated. +</para> + +<variablelist> + <varlistentry> + <term><guilabel>Check Arguments</guilabel></term> + <listitem> + <para> + When this option is selected, C-format strings in the original and + the translation are checked to ensure the number of + format sequences and the order are consistent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Check Accelerator</guilabel></term> + <listitem> +<para>When this option is selected, &kbabel; checks if the number +accelerator characters is identical in both the original and the +translated string. Note that accelerator marker is & (but not in +every programming toolkit). See the <link +linkend="preferences-project-miscellaneous">Miscellaneous</link> section below +to find how to change a keyboard accelerator.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Check Equation</guilabel></term> + <listitem> + <para> + This is a feature for the &kde; project development. + <filename>.desktop</filename> files are simply + text files which store various parameters in + <literal>value=key</literal> format. Some of + these <literal>key</literal>s are translatable. + The only restriction is to maintain the left + side of equality unchanged. Equation check + allows you to spot many errors determined + by the fuzzy <command>msgmerge</command> algorithm. + Note that there are situations where this function + generates false errors on some PO-files. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Look for Translated Context Info</guilabel></term> + <listitem> +<para> Some original messages are marked with context information to +mark them as being unique even if they represent same word. This is +because many simple words, such as <quote>Save</quote>, are translated +into many languages. Context information is marked with +<literal>_:</literal>. Many unexperienced translators translate the +context information and fill their PO files with garbage. Check this +box to make sure you will be warned about these errors in a +file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Check Plural Forms</guilabel></term> + <listitem> + <para> + If you are translating &kde; project, it uses a special kind of + syntax for specifying plural forms of messages. This check automatically + counts the number of forms in <acronym>msgstr</acronym> and + compares it with the number specified in +<link linkend="preferences-project-identity"><guilabel>Identity</guilabel></link> +tab. Incorrect number of plural forms can result in crash of an application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Beep on error</guilabel></term> + <listitem> + <para> + Your system bell will beep when you switch + on entries with errors like those described above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Change text color on error</guilabel></term> + <listitem> + <para> + This is another type of warning about + errors in current message. It is a good solution for those who are + hearing impaired or dislike bell noise. See also the + <link linkend="preferences-editor-appearance">Appearance</link> tab + to find out how to change the text color on errors. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect3> + +<sect3 id="preferences-editor-appearance"> +<title>Appearance</title> + +<screenshot> +<screeninfo>Dialog Edit Appearance</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_edit_appearance.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Edit Appearance</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +These options let +you configure the appearance for the message editor. In upper part there +are 4 checkboxes: +</para> + +<variablelist> + <varlistentry> + <term><guibutton>Highlight syntax</guibutton></term> + <listitem><para> + Setting this option will enable syntax highlighting for + special characters, accelerators and text background in the msgid viewer + and msgstr editor. If don't have a monochrome display or have a visual impairment, you should enable this option. +</para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Highlight background</guibutton></term> + <listitem><para> + The background will be highlighted only for existing characters in + the msgid and msgstr. This includes spaces. This is useful if you + don't want to see the surrounding quotes (see below) for the <acronym>PO</acronym> entry, and you will still + be able to observe starting and ending spaces in a text line. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Mark whitespaces with points</guibutton></term> + <listitem><para> + When you feel the need to count spaces + and background highlighting is not your taste then you can + check this option to have a point sign drawn in the middle of + whitespace characters. Note that the point is a point sign in the + center of a character box and is not a decimal point. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Show surrounding quotes</guibutton></term> + <listitem><para> + If you think that viewing the terminal characters in msgstr or + msgid's text line is better for you then check this option to view + the surrounding quotes for every text line.</para> + <para>If you are experienced editing <acronym>PO</acronym> files with + ordinary text editors you may feel safer if you can track starting and + ending double quotes in <acronym>PO</acronym> entry lines. + </para></listitem> + </varlistentry> +</variablelist> + +<para> +For the different items in edited text there are different color choices +to make editing easy. Colors can be changed by clicking on color-picker +buttons. From the 'select color' dialogs you can choose from standard +colors, custom colors or just pick a color from any part of your screen. +</para> + +<variablelist> + <varlistentry> + <term><guilabel>Background color</guilabel></term> + <listitem><para> + This sets the background color for characters in the MsgID view + and the MsgStr editor. To change the general background color + of edit boxes you must use the &kcontrolcenter;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Color for quoted characters</guilabel></term> + <listitem><para> + Here you can adjust the color for escaped characters like + (<literal>\"</literal>) double quotes or (<literal>\n</literal>) newline. </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Color for syntax errors</guilabel></term> + <listitem><para> + This is the color for the entire text entry if errors are + detected when you try to save <acronym>PO</acronym> file. Errors are + triggered by not terminating identically both <acronym>msgid</acronym> and <acronym>msgstr</acronym>, or + escaping characters incorrectly. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Color for c-format characters</guilabel></term> + <listitem><para> + This sets the color for a characters sequence like in + C language <function>printf</function> or <function>scanf</function> functions. In general these start with (<literal>%</literal>) percent char and are continued by one char. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Color for keyboard accelerators</guilabel></term> + <listitem><para> + Keyboard accelerators start with (&) <quote>ampersand</quote> + character in &kde; but if you are translating for other projects there might be an different character marking the accelerator key. +See <link linkend="preferences-project-miscellaneous">Miscellaneous</link> +section below to find how to change keyboard accelerator. + </para></listitem> + </varlistentry> +</variablelist> + +<para> The status for the current edited entry is marked by three +<acronym>LED</acronym>s. For your convenience you can choose where to +put these <acronym>LED</acronym>s—either on the statusbar or in +the editor section (between the msgid and msgstr entry). If have +difficulties viewing some colors or you want to be able to track +<acronym>LED</acronym> status changes easily without moving your eye +you can select the preferred color using the color button chooser. +</para> + +</sect3> + +</sect2> + +<sect2 id="preferences-search"> +<title>Search</title> + +<screenshot> +<screeninfo>Dialog Search</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_search.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Search</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +The search section allows you to customize various settings +for searching in previously translated strings. +</para> + +<para>General settings are common for all search types. If you check +the <guibutton>Automatically start search</guibutton> option then the +search is automatically started whenever you switch to another entry +in the editor. Currently, there are three possibilities you can choose +from, but since &kbabel; can use dictionary plugins the available +dictionaries depend on those installed. Using +<menuchoice><guimenuitem>Settings</guimenuitem> <guimenuitem>Configure +Dictionary</guimenuitem> <guimenuitem>...</guimenuitem></menuchoice> +you can configure every search plugin.</para> + +<para>The dictionary plugins installed by default are:</para> + +<variablelist> +<varlistentry> +<term>&kde; Database Search Engine</term> +<listitem> +<para>This new method is still in alpha stage of development + and is based on &kbabeldict; which accompanies &kbabel;. + See &kbabeldict; documentation for further info on + configuring the search engine. + </para></listitem> +</varlistentry> + +<varlistentry> +<term>PO Compendium</term> +<listitem><para>The compendium is a normal <acronym>PO</acronym> file, + which should contain a list of standard translations from your translation + team. If you don't have one, you can also use a file that contains all + the translations from your team (⪚ the <filename>$lang.messages</filename> + file in the &kde; Project, that can be found at + <ulink url="http://i18n.kde.org/po_overview/">i18n.kde.org</ulink>). + </para></listitem> +</varlistentry> + +<varlistentry> +<term>PO Auxiliary</term> +<listitem><para>The auxiliary should help you find the + context of a translation by looking up the same message in a message + catalog of the same package but translated to another language. This way + you can have a look how this message is translated in another language. + </para></listitem> +</varlistentry> +</variablelist> + +<para> +You can also start searching manually by choosing an +entry in the popup menu that appears, either by clicking +<menuchoice> +<guimenu>Dictionaries</guimenu><guimenuitem>Search Text</guimenuitem> +<guimenuitem>PO Compendium</guimenuitem></menuchoice> +or by keeping the search button on the toolbar pressed down for a while. +</para> + +</sect2> + +<sect2 id="preferences-diffmode"> +<title>Diff</title> + +<screenshot> +<screeninfo>Dialog Diff</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_diff.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Diff</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The <guilabel>Diff</guilabel> section holds settings how to +display differences in msgids. </para> + +<para>Every difference can be displayed by two added parts and by characters removed from the text. For both you can specify the method of display and the color to be used. <guilabel>Highlighted</guilabel> means that the background of the corresponding characters will be shown in the selected color, while +<guilabel>Underlined</guilabel>(for added characters) or <guilabel>Stroked Out</guilabel> +(for removed characters) will denote the changed parts by colored lines. +</para> +<para> +Diff mode needs to find the original <acronym>msgid</acronym> to compare +with. For this purpose, &kbabel; can use the <link linkend="database">translation database</link> +if you turn in on by enabling <guilabel>Use messages from Translation Database</guilabel>. +A second possibility is to use a tree of original PO files and specifying the root of +the tree in <guilabel>Base folder for diff files</guilabel>. +</para> +</sect2> + +<sect2 id="preferences-fonts"> +<title>Fonts</title> + +<screenshot> +<screeninfo>Dialog Fonts</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_fonts.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Fonts</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +This is a standard &kde; font chooser dialog with a little addition. You can +select to view only fixed fonts by checking the +<guibutton>Show only fixed fonts</guibutton> option. +This is highly recommended for easy translating. The font dialog lets you set +font family, style, size and encoding. The bottom box shows a preview of the +current font for user convenience. +</para> +</sect2> + +</sect1> + +<sect1 id="preferences-project-wizard"> +<title>New Project Wizard</title> + +<sect2 id="preferences-project-wizard-basic"> +<title>Page 1</title> + +<screenshot> +<screeninfo>Project Wizard Page 1</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_wizard_page1.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Wizard Page 1</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +The first page of the wizard ask about the basic data of the project. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Project name</guilabel></term> +<listitem><para> +Enter here the name of the project, as it will be displayed in &kbabel;'s menu. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Configuration file name</guilabel></term> +<listitem><para> +Select here a file for holding your project settings. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Language</guilabel></term> +<listitem><para> +Select or enter here the language name used by this project. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Project type</guilabel></term> +<listitem><para> +Select here the type of your project. +</para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="preferences-project-wizard-catman"> +<title>Page 2</title> + +<screenshot> +<screeninfo>Project Wizard Page 2</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_wizard_page2.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Wizard Page 2</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +The second page of the wizard asks about settings related to the +Catalog Manager. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Base folder for PO files</guilabel></term> +<listitem><para> +Select the base folder where your PO files are. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Base folder for POT files</guilabel></term> +<listitem><para> +Select the base folder where your POT files are. +</para></listitem> +</varlistentry> +</variablelist> + +<para> +Type in or select the folders that contains all your <acronym>PO</acronym> and respectively +<acronym>POT</acronym> files. The files and the folders in these folders will then be +merged into one tree in &catalogmanager; window. +</para> + + +</sect2> + +<sect2> +<title>Checking Project Stettings</title> + +<important><para> +As written earlier in this chapter, unfortunately the wizard is very simple and +therefore fails to ask for some important settings. +</para></important> + +<para> +Now that you have <quote>finished</quote> your new project, you should verify the main settings in +<menuchoice><guimenu>Project</guimenu> <guimenuitem>Configure...</guimenuitem></menuchoice>. +Especially select the <guilabel>Identity</guilabel> page and fix the team email address in +<guilabel>Language mailing list</guilabel>. +(The default one created by the wizard from the language setting is only useful if you are part of a &GNU; project.) +</para> + +<para> +If the project settings are not for KDE, it is recommended that you check the +<guilabel>Save</guilabel> page and checks the settings there. +</para> + +</sect2> + +</sect1> + +<sect1 id="preferences-project-settings"> +<title>Project Settings</title> + +<para> To show the project setting dialog choose +<menuchoice><guimenu>Project</guimenu> <guimenuitem>Configure...</guimenuitem></menuchoice> +from &kbabel;'s or &catalogmanager;'s menu. It uses a +structured configuration dialog which makes it very easy to find an +option without having to perform an extensive search for it.</para> + +<para>The left side of the preferences dialog lists the categories of +customizable items and the right side shows the corresponding tab for +the selected category. &kbabel; keeps changes if you move between +categories, so when you're finally happy click the +<guibutton>OK</guibutton> button. At any time you can use quick +help—just click on the question mark on the title bar and, +after the cursor has changed to an arrow with a question mark, +click on a button, label, or preference entry to find out more +about it.</para> + +<note><para> +Pages for settings for &kbabel; (the editor) and for &catalogmanager; +are in the list. +</para></note> + +<sect2 id="preferences-project-identity"> +<title>Identity</title> + +<para>These settings are for &kbabel;.</para> + +<para>This section allows you to set standard fields for every +translated <acronym>PO</acronym> file. These are your name, email +address, full language name, email address for your translation team +mailing list. There is also a timezone field to track your +<quote>last modified</quote> time for <acronym>PO</acronym> files. +You can specify it as character sequence like <acronym>EEST</acronym> +or offset from <acronym>GMT</acronym> time like +0200 (&ie; for +Romania). This information is used when updating file headers. You +can find the options that control what fields in the header should be +updated in the <link linkend="preferences-project-save">Save</link> section of +the Preferences dialog.</para> + +<warning><para>Character sequences for timezones are not standardized. +So you should not use the string set here in time specification for +saving in <link linkend="preferences-project-save">Save</link> tab. You should +use <literal>%z</literal> instead.</para></warning> + +<variablelist> +<varlistentry> +<term><guilabel>Number of singular/plural forms</guilabel></term> +<listitem> +<para> Use this for setting number of plural forms for your +language. For example, it is 2 for German (one for the singular and +one for the plural form).</para> + +<note><para>This feature is currently implemented only for plural forms format used in &kde;. It does not work with &GNU; gettext plural forms.</para></note> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="preferences-project-save"> +<title>Save</title> + +<para>These settings are for &kbabel;.</para> + +<para><remark> +TODO This seems to document only the "General" tab but not the "Header" and "Copyright" ones +</remark></para> + +<para> +This section allows you to edit the options for <acronym>PO</acronym> file saving. The first +group of checkboxes controls general behavior for actions +performed in <acronym>PO</acronym> file saving. +</para> + +<variablelist> + <varlistentry> + <term><guibutton>Update header when saving</guibutton></term> + <listitem><para> +Check this button, to update the header information of the file +every time it is saved. The header normally keeps information +about the date and time the file was last updated,the last translator +etc. You can choose which information you want to update from the +<guilabel>Fields to update</guilabel> checkboxes area below. Fields +that do not exist are added to the header. If you want to add +additional fields to the header you can edit the header manually by +choosing <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Edit +Header</guimenuitem></menuchoice> in the editor window. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Check syntax of file when saving</guibutton></term> + <listitem><para> +Check this to automatically check syntax of file with +<userinput><command>msgfmt</command> --statistics</userinput> when +saving a file. You will only get a message if an error occurred. You +should keep this validation enabled unless you know what you are doing. + </para></listitem> + </varlistentry> +</variablelist> + +<para>If you do not want to touch some fields in a <acronym>PO</acronym> +file header or want to force updating of specific fields, there are five +checkboxes which control this: revision date, <acronym>PO</acronym> file +language, text encoding, last translator name, charset. If a field +does not exist, it is appended to the header. If you want to add other +information to the header, you have to edit the header manually by +choosing <menuchoice><guimenu>Edit</guimenu><guimenuitem>Edit +Header</guimenuitem></menuchoice> in the editor window. Deactivate +<guibutton>Update header when saving</guibutton> above if you don't +want to have the header updated.</para> + +<para>For date and time of the header field +<emphasis>PO-Revision-Date</emphasis> you can choose one of the +formats: <guilabel>Default</guilabel>, <guilabel>Local</guilabel>, <guilabel>Custom</guilabel>.</para> + +<important><para> +You should keep the default setting of <guilabel>Default</guilabel>. The two other settings +make that the generated <acronym>PO</acronym> file is not a standard &GNU; gettext <acronym>PO</acronym> file +anymore, so this should be avoided. +</para></important> + +<itemizedlist> + <listitem><para> + <guilabel>Default</guilabel> is the format normally used in <acronym>PO</acronym> files. + </para></listitem> + <listitem><para> + <guilabel>Local</guilabel> is the format specific to your country. + </para></listitem> + <listitem><para> + <guilabel>Custom</guilabel> lets you define your own format, where you + can use the following C-like format strings: + <table> + <title>Year</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%y</entry><entry>year</entry><entry>00 to 99</entry> + </row> + <row> + <entry>%Y</entry><entry>year</entry><entry>0001 to 9999</entry> + </row> + </tbody> + </tgroup> + </table> + <table> + <title>Month</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%m</entry><entry>month of year</entry><entry>01 to 12</entry> + </row> + <row> + <entry>%f</entry><entry>month of year</entry><entry>1 to 12</entry> + </row> + <row> + <entry>%b,%h</entry><entry>month abbreviation</entry><entry>Jan to Dec</entry> + </row> + </tbody> + </tgroup> + </table> + <table> + <title>Day</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%j</entry><entry>day of the year</entry><entry>001 to 366</entry> + </row> + <row> + <entry>%d</entry><entry>day of month</entry><entry>01 to 31</entry> + </row> + <row> + <entry>%e</entry><entry>day of month</entry><entry>1 to 31</entry> + </row> + <row> + <entry>%a</entry><entry>weekday abbreviation</entry><entry>Sun to Sat</entry> + </row> + </tbody> + </tgroup> + </table> + <table> + <title>Hour</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%H</entry><entry>hour</entry><entry>00 to 23</entry> + </row> + <row> + <entry>%k</entry><entry>hour</entry><entry>0 to 23</entry> + </row> + <row> + <entry>%i</entry><entry>hour</entry><entry>1 to 12</entry> + </row> + <row> + <entry>%I</entry><entry>hour</entry><entry>01 to 12</entry> + </row> + <row> + <entry>%p</entry><entry></entry><entry>AM or PM</entry> + </row> + </tbody> + </tgroup> + </table> + <table> + <title>Minute, Second, Timezone</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%M</entry><entry>minute</entry><entry>00 to 59</entry> + </row> + <row> + <entry>%S</entry><entry>second</entry><entry>00 to 59</entry> + </row> + <row> + <entry>%Z</entry><entry>timezone</entry><entry>(given in identity settings)</entry> + </row> + <row> + <entry>%z</entry><entry>timezone</entry><entry>(numeric offset as specified by system settings)</entry> + </row> + </tbody> + </tgroup> + </table> + </para></listitem> +</itemizedlist> + +<note><para> +The option to select the date format for the <acronym>PO</acronym> file is considered to be deprecated, +and will probably be removed in a future version of KBabel. +</para></note> + +<para>The lower group covers encoding options for <acronym>PO</acronym> +files when saving. If you work on the &kde; project you should be aware +that at least <acronym>PO</acronym> files <emphasis>must</emphasis> be UTF-8 encoded in &kde;. +Alternatively you can select the encoding corresponding to your locale. +If, for some reason, you do not want to accidentally change the current PO +file encoding, turn on <guibutton>Keep the encoding of the +file</guibutton>.</para> + +<caution><para> +For reason of informtation interchange, &GNU; gettext limits the encodings allowed for a +<acronym>PO</acronym> file. &kbabel; does not know of this restriction, so the encoding +correspondig to your locale might not be suitable. (UTF-8 is always supported by &GNU; gettext.) +</para></caution> + +</sect2> + +<sect2 id="preferences-project-spellcheck"> +<title>Spell Check</title> + +<para>These settings are for &kbabel;.</para> + +<para>Here you can set your spell checking preferences. This is of +interest if you have a dictionary file for the language you are +translating to. Below are the items to consider setting:</para> + +<variablelist> + <varlistentry> + <term><guibutton>Create root/affix combinations not in dictionary</guibutton></term> + <listitem><para> + For new words added to the personal dictionary, + the spell checker will create root/affix + combinations to match more than one word (variations). + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Consider run-together words as spelling errors</guibutton></term> + <listitem><para> + If this is turned on, joined words will be treated + as errors. However, such words are very common in + the German language, which have a very large number of + compound words, so it should be left turned off in that case. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Dictionary</guilabel></term> + <listitem><para> + From the popup list you can choose which dictionary to use. Note + that you must install an appropriate dictionary for your language. + Check your ispell or aspell distribution to find out if you have + one. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Encoding</guilabel></term> + <listitem> +<para> + Here you choose the encoding for your text. This option is passed + to the spellchecker, and is used as the encoding for your words + dictionary. + See the <ulink url="help:/kspell">kspell</ulink> documentation for + more details. +</para> +<note><para> +The encoding selected here is not linked to encodings of the +<acronym>PO</acronym> files. Depending on the spellchecker +(especially in the case of <command>ispell</command>), +you might not have much choice for the encoding. +(For example, a few Western European languages can only work +with <command>ispell</command> when using ISO-8859-1.) +</para></note> + </listitem> + + </varlistentry> + <varlistentry> + <term><guilabel>Client</guilabel></term> + <listitem><para> + Backend program to use for spell checking. Currently either + <command>ispell</command> (International Ispell) or aspell. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Remember ignored words</guibutton></term> + <listitem><para> + Keep track of user-ignored words when spell-checking + <acronym>PO</acronym> files. It is very convenient to ignore the abbreviations or strange letter combinations you meet in &GUI; interfaces. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>File to store ignored words</guilabel></term> + <listitem><para> + Here you can set location of the file for ignored words. Click + on the folder icon to the right of the edit box. The default is + <filename>$<envar>HOME</envar>/.kde/share/apps/kbabel/spellignores</filename>, + where <filename>$<envar>HOME</envar></filename> is your home folder. + </para></listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="preferences-project-source"> +<title>Source reference</title> + +<para>These settings are for &kbabel;.</para> + +<screenshot> +<screeninfo>Project Settings, source reference</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_source.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, source reference</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +This dialog is for setting how KBabel should construct the full path from each source references, +which are in the comments of each entry of a <acronym>PO</acronym> file. +</para> + +<sect3> +<title>Dialog elements</title> + +<para> +In the edit line <guilabel>Base folder for source code</guilabel>, you can set a +base folder where the source code of your project is. This defines the value of the variable +<userinput>@CODEROOT@</userinput>, which is described below. +</para> + +<para> +In the group <guilabel>Path Patterns</guilabel>, you can define patterns or rules +to construct the paths with the help of a few variables: +<userinput>@CODEROOT@</userinput>, <userinput>@PACKAGEDIR@</userinput>, +<userinput>@PACKAGE@</userinput>, <userinput>@COMMENTPATH@</userinput>, +<userinput>@POFILEDIR@</userinput>, which are defined below. +</para> + +<note><para> +The variable <userinput>@PODIRFILE@</userinput> was introduced in &kbabel; version 1.11.1 (for &kde; 3.5.1). +</para></note> + +<para> +With the button <guibutton>Add</guibutton>, you can add the line from the text box +to the list of used path patterns. With the button <guibutton>Remove</guibutton>, +you can remove the selected pattern from the list. With the buttons +<guibutton>Up</guibutton> and <guibutton>Down</guibutton>, you can change the priority of +the path patterns. +</para> + +</sect3> + +<sect3> +<title>The variables</title> + +<itemizedlist> +<listitem><para> +<userinput>@CODEROOT@</userinput>: The base folder of the source code. +</para></listitem> +<listitem><para> +<userinput>@PACKAGEDIR@</userinput>: The folder of the package (i.e. <acronym>PO</acronym> file). +</para></listitem> +<listitem><para> +<userinput>@PACKAGE@</userinput>: The package name (i.e. <acronym>PO</acronym> file name without extension). +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>: The folder of the <acronym>PO</acronym> file. +</para></listitem> +<listitem><para> +<userinput>@COMMENTPATH@</userinput>: The relative path given as source reference in the comment of an entry of the <acronym>PO</acronym> file. +</para></listitem> +</itemizedlist> + +<important><para> +The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> have similar +meaning but not the same result. The variable <userinput>@POFILEDIR@</userinput> +will always hold the folder of <acronym>PO</acronym> file, +<userinput>@PACKAGEDIR@</userinput> might not. If the <acronym>PO</acronym> file was loaded +by the help of the &catalogmanager; then <userinput>@PACKAGEDIR@</userinput> has only the part of +the path, based on the <acronym>PO</acronym> base path defined for the &catalogmanager; +<link linkend="preferences-project-folders">(see below)</link>. +</para></important> + +<note><para> +The variables <userinput>@CODEROOT@</userinput> and <userinput>@POFILEDIR@</userinput> can only be used at +the beginning of a pattern to be useful. The variable <userinput>@COMMENTPATH@</userinput> can only be used at the +end of a pattern and is nearly mandatory. +The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> +should not be used in the same pattern. The variables <userinput>@CODEROOT@</userinput> and <userinput>@POFILEDIR@</userinput> should not be used in the same pattern either. +</para></note> + +</sect3> + +<sect3> +<title>The default path patterns</title> + +<para> +From &kbabel; 1.11.1 (of &kde; 3.5.1) on, there are five default path patterns: +</para> + +<itemizedlist> +<listitem><para> +<userinput>@PACKAGEDIR@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGEDIR@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>/../<userinput>@COMMENTPATH@</userinput> +</para></listitem> +</itemizedlist> + +<note><para> +&kde; projects need typically the third pattern. +The last pattern is typical for &GNU; projects, where the source references are related to +the parent of the directory where the PO file is. +</para></note> + +</sect3> + +<sect3> +<title>Creating New Path Patterns</title> + +<para> +In most cases the default path patterns should be enough, whatever +the project is for KDE (assuming that you have set the correct base directory) +or if the project is a &GNU; one (or structured like a &GNU; project). +</para> + +<note><para> +For &kde;, some <acronym>PO</acronym> files do not contain enough information +(including the file path and name) for &kbabel; to find the right source file +that is supposed to be refered. To fix that you would need precise path patterns +for such files, which is nearly impossible to define by the numbers of such files +in &kde;. But if you work often with such a file, may be it is worth to set +a path pattern explicitely for supporting that <acronym>PO</acronym> file. +</para></note> + +<para> +For creating your own path patterns, you can use the variables defined above, +but apart <userinput>@COMMENTPATH@</userinput> not any variable is mandatory to use. +(To be exact, <userinput>@COMMENTPATH@</userinput> is not mandatory either, +but not using it will probably lead to no result.) +</para> + +<para> +An example of path pattern could be that you want to display the source reference +of &kde;'s file desktop_kdebase.po. In that case you will probably need a path pattern like: +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGEDIR@</userinput>/kdebase/<userinput>@COMMENTPATH@</userinput> +(compared to one of the default path patterns, the sequence <userinput>@PACKAGE@</userinput> has been +replaced by kdebase). +</para> + +<para> +In case of really complex problems you can, of course, define an absolute path +without any variables beside <userinput>@COMMENTPATH@</userinput>, like for example: +/home/usr/kde-source/kdebase/<userinput>@COMMENTPATH@</userinput> assuming that +/home/usr/kde-source/kdebase is the path where the kdebase source module is. +</para> + +</sect3> + +</sect2> + +<sect2 id="preferences-project-miscellaneous"> +<title>Miscellaneous</title> + +<para>These settings are for &kbabel;.</para> + +<para> +<guilabel>Miscellaneous</guilabel> section +holds &kbabel; settings that do not fit anywhere else. +</para> + +<variablelist> + <varlistentry> + <term><guilabel>Marker for keyboard accelerator</guilabel></term> + <listitem><para> + Here you can select your own character to serve + as the keyboard accelerator indicator in a &GUI;. + By default it is & (ampersand), but in some + programming toolkits it may vary. + For example, in Gnome/GTK translations the underscore + character <quote>_</quote> + is the marker for the keyboard accelerator. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Regular expression for context information</guilabel></term> + <listitem><para> + For inexperienced users "regular expression" may sound strange. + So you are advised to change the default value + only if you know what you are doing. Some &GUI; programming + toolkits provide their own context information description + methods. Consult an experienced developer if you + translate <acronym>PO</acronym> files other than standard &kde; files. + For the sake of completeness I will "translate" for you what the + default regular expression means: + "the text matches if it starts with _: and is followed + by one or more characters and ends with a newline". + </para></listitem> + </varlistentry> +</variablelist> +</sect2> + +<!-- Catalog Manager project settings --> + +<sect2 id="preferences-project-folders"> +<title>Project folders</title> + +<para>These settings are for &catalogmanager;.</para> + +<para> +Here are two edit lines with folder buttons. +Type in or select the folders that contains all your <acronym>PO</acronym> and respectively +<acronym>POT</acronym> files. The files and the folders in these folders will then be +merged into one tree in Catalog Manager window. +</para> + +<para> +Below you can turn on and off if: +</para> + +<variablelist> + <varlistentry> + <term><guibutton>Open files in new window</guibutton></term> + <listitem><para> + If this is activated all files that are opened from the Catalog + Manager are opened in a new window. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Kill processes on exit</guibutton></term> + <listitem><para> + If you check this, &kbabel; tries to kill the processes that are not + exited already when the program closes by sending a kill signal to them. + <note><para> + It's not guaranteed that the processes are killed. + </para></note> + </para></listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Create index for file contents</guibutton></term> + <listitem><para> + If you check this, &kbabel; will create an index of contents for every + file in the tree. This index is then used in find/replace operations. + <warning><para>There is a large speed trade-off. If you enable + <guibutton>Create index for file contents</guibutton>, the updating of + file information will be much slower. On the other hand, it speeds up + find/replace operations considerably.</para></warning> + </para></listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="preferences-project-folder-commands"> +<title>Folder Commands</title> + +<para>These settings are for &catalogmanager;.</para> + +<screenshot> +<screeninfo>Project Settings,folder commands</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_folder_commands.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, folder commands</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +Here you can insert commands you want to execute in folders from the +Catalog Manager. The commands are then shown in the submenu +<menuchoice><guimenuitem>Commands</guimenuitem></menuchoice> +in the Catalog Manager's context menu. + +</para><para> +Insert in the <guilabel>Command Label</guilabel> field the +label of the command. The label can be chosen freely and is only used to be displayed +in the menu. In the <guilabel>Command</guilabel> field insert the command you want to +have executed when selecting the corresponding menu item. Then press the <guibutton>Add</guibutton> +button to add the command to your available commands. +To edit a command, select it, press the +<guibutton>Edit</guibutton> button and press <guibutton>Add</guibutton> after you have +finished. To remove a command, select it from the list and press the +<guibutton>Remove</guibutton> button. If you want a different order in the contextual +submenu, you can use the up and down buttons. + +</para><para> +The command is executed through your default shell, so you can execute +multiple commands at once by separating them with a semicolon, and you can set environment +variables if you need to. The commands are executed in the (<acronym>PO</acronym> file) folder you have +selected in the Catalog Manager. + +</para><para> +The following strings will be replaced in a command: +</para> + +<itemizedlist> + <listitem><para> + <userinput>@PACKAGE@</userinput>: The name of the folder without path + </para></listitem> + <listitem><para> + <userinput>@PODIR@</userinput>: The name of the <acronym>PO</acronym>-folder with path + </para></listitem> + <listitem><para> + <userinput>@POTDIR@</userinput>: The name of the template folder with path + </para></listitem> +</itemizedlist> + +<para> +E.g.: If you want to execute <command>make</command> and then <command>make +install</command> you could insert in <userinput>Make install</userinput> in the +<guilabel>Name</guilabel> field, and <userinput>make; make install</userinput> +in the <guilabel>Command</guilabel> field. If you then select +<menuchoice><guimenuitem>Commands</guimenuitem> +<guimenuitem>Make install</guimenuitem></menuchoice> +from the context menu of a folder, the commands listed above will be +executed in that folder. +</para> +</sect2> + +<sect2 id="preferences-project-file-commands"> +<title>File Commands</title> + +<para>These settings are for &catalogmanager;.</para> + +<screenshot> +<screeninfo>Project Settings, file commands</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_file_commands.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, file commands</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +Here you can insert the commands you want to execute on files from the Catalog +Manager. The commands are then shown in the submenu +<menuchoice><guimenuitem>Commands</guimenuitem></menuchoice> in the Catalog +Manager's context menu. +</para> + +<para> +Insert in the <guilabel>Command Label</guilabel> field the label of the command. The label can be +chosen freely and is only used to be displayed in the menu. In the +<guilabel>Command</guilabel> field insert the command you want to have executed when +selecting the corresponding menu item. Then press the <guibutton>Add</guibutton> button +to add the command to your available commands. To edit a command, select it, press +the <guibutton>Edit</guibutton> button and press the <guibutton>Add</guibutton> button after you have +finished. To remove a command, select it from the list and press the +<guibutton>Remove</guibutton> button. If you want a different order in the contextual +submenu, you can use the up and down buttons. + +</para><para> +The command is executed through your default shell, so you can execute +multiple commands at once by separating them with a semicolon, and you can +set environment variables, if you need. The commands are executed in the +(<acronym>PO</acronym> file) folder, in which the file, you have selected in the Catalog +Manager, is. + +</para><para> +The following strings will be replaced in a command: +</para> + +<itemizedlist> + <listitem><para> + <userinput>@PACKAGE@</userinput>: The name of the file without path and extension + </para></listitem> + <listitem><para> + <userinput>@POFILE@</userinput>: The name of the <acronym>PO</acronym> file with path and extension + </para></listitem> + <listitem><para> + <userinput>@POTFILE@</userinput>: The name of the corresponding template file + with path and extension + </para></listitem> + <listitem><para> + <userinput>@PODIR@</userinput>: The name of the folder the <acronym>PO</acronym> file is in, with path + </para></listitem> + <listitem><para> + <userinput>@POTDIR@</userinput>: The name of the folder the template file is + in, with path + </para></listitem> +</itemizedlist> +<para> +For example, if you want to merge the template file into your <acronym>PO</acronym> file you could +insert <userinput>Merge</userinput> in the <guilabel>Name</guilabel> field and +<userinput>msgmerge @POFILE@ @POTFILE@ > @PACKAGE@.new && mv @PACKAGE@.new +"@PACKAGE@.po</userinput> in the <guilabel>Command</guilabel> field. +If you then select +<menuchoice><guimenuitem>Commands</guimenuitem><guimenuitem>Merge</guimenuitem></menuchoice> +from a file's context menu, the <acronym>PO</acronym> file will be merged with its template file. +</para> +</sect2> + +<sect2 id="preferences-project-catalog-manager"> +<title>Catalog Manager</title> + +<para>These settings are for &catalogmanager;.</para> + +<screenshot> +<screeninfo>Project Settings, &catalogmanager;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_catman.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, &catalogmanager;</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The checkboxes switches on or off the corresponding column of the &catalogmanager;'s view.</para> + +</sect2> + +<sect2 id="preferences-project-diff"> +<title>Diff</title> + +<para>These settings are for &catalogmanager;.</para> + +<screenshot> +<screeninfo>Project Settings, diff</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_diff.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, diff</phrase></textobject> +</mediaobject> +</screenshot> + +<para><remark>TODO</remark></para> + +</sect2> + +</sect1> +</chapter> +<!-- +Local Variables: +mode: xml +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/kbabel/preverror.png b/doc/kbabel/preverror.png Binary files differnew file mode 100644 index 00000000..d589b53b --- /dev/null +++ b/doc/kbabel/preverror.png diff --git a/doc/kbabel/prevfuzzy.png b/doc/kbabel/prevfuzzy.png Binary files differnew file mode 100644 index 00000000..2e4cedfa --- /dev/null +++ b/doc/kbabel/prevfuzzy.png diff --git a/doc/kbabel/prevfuzzyuntrans.png b/doc/kbabel/prevfuzzyuntrans.png Binary files differnew file mode 100644 index 00000000..cf6f43d4 --- /dev/null +++ b/doc/kbabel/prevfuzzyuntrans.png diff --git a/doc/kbabel/previous.png b/doc/kbabel/previous.png Binary files differnew file mode 100644 index 00000000..167e39e7 --- /dev/null +++ b/doc/kbabel/previous.png diff --git a/doc/kbabel/prevuntranslated.png b/doc/kbabel/prevuntranslated.png Binary files differnew file mode 100644 index 00000000..796a4e3d --- /dev/null +++ b/doc/kbabel/prevuntranslated.png diff --git a/doc/kbabel/redo.png b/doc/kbabel/redo.png Binary files differnew file mode 100644 index 00000000..d6b3e8f1 --- /dev/null +++ b/doc/kbabel/redo.png diff --git a/doc/kbabel/roughtranslation.png b/doc/kbabel/roughtranslation.png Binary files differnew file mode 100644 index 00000000..cd96526c --- /dev/null +++ b/doc/kbabel/roughtranslation.png diff --git a/doc/kbabel/snap1.png b/doc/kbabel/snap1.png Binary files differnew file mode 100644 index 00000000..55e3c9cd --- /dev/null +++ b/doc/kbabel/snap1.png diff --git a/doc/kbabel/snap_catalogmanager.png b/doc/kbabel/snap_catalogmanager.png Binary files differnew file mode 100644 index 00000000..20aff2ec --- /dev/null +++ b/doc/kbabel/snap_catalogmanager.png diff --git a/doc/kbabel/snap_kbabeldict.png b/doc/kbabel/snap_kbabeldict.png Binary files differnew file mode 100644 index 00000000..58d9db14 --- /dev/null +++ b/doc/kbabel/snap_kbabeldict.png diff --git a/doc/kbabel/snap_kbabeldict2.png b/doc/kbabel/snap_kbabeldict2.png Binary files differnew file mode 100644 index 00000000..562862e7 --- /dev/null +++ b/doc/kbabel/snap_kbabeldict2.png diff --git a/doc/kbabel/stop.png b/doc/kbabel/stop.png Binary files differnew file mode 100644 index 00000000..1cabc6e9 --- /dev/null +++ b/doc/kbabel/stop.png diff --git a/doc/kbabel/top.png b/doc/kbabel/top.png Binary files differnew file mode 100644 index 00000000..b626bf42 --- /dev/null +++ b/doc/kbabel/top.png diff --git a/doc/kbabel/transsearch.png b/doc/kbabel/transsearch.png Binary files differnew file mode 100644 index 00000000..06d5852c --- /dev/null +++ b/doc/kbabel/transsearch.png diff --git a/doc/kbabel/undo.png b/doc/kbabel/undo.png Binary files differnew file mode 100644 index 00000000..f5ad210d --- /dev/null +++ b/doc/kbabel/undo.png diff --git a/doc/kbabel/using.docbook b/doc/kbabel/using.docbook new file mode 100644 index 00000000..091361e6 --- /dev/null +++ b/doc/kbabel/using.docbook @@ -0,0 +1,791 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> --> +<!-- Uncomment the previous two lines to validate this document --> +<!-- standalone. Be sure to recomment them before attempting to --> +<!-- process index.docbook --> + +<chapter id="using-kbabel"> +<chapterinfo> +<!-- Fill in this section if this document has a different author --> +<authorgroup> +<author> +<personname><firstname></firstname><surname></surname></personname> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</chapterinfo> + + +<title>Using &kbabel;</title> + +<sect1 id="using-introduction"> +<title>Introduction</title> + +<para>Usually program messages and documentation are written in +English. Using a framework made of a set of tools and libraries, it +is possible to have your favorite applications speak your native +non-English language. This process of adapting an application to a +specific language is known as localization. The localization process +includes translating the program's interfaces and documentation to the +various languages users need and, in some countries or regions, making +the inputs and outputs conform to particular conventions. &kbabel; is +a tool which will assist you in the localization process to +make an application's interface speak many languages.</para> + +<para> Every internationalization-aware program makes available for +translation one or more message-catalog files. The extension of these +files is <literal role="extension">.pot</literal>. +<acronym>POT</acronym> is an acronym for <quote>Portable Object +Template</quote>.</para> + +<para> +Each translator takes a copy of one of these <acronym>POT</acronym> templates and +begins to fill in the blanks: each message is translated into the +language desired. The file containing the translated text is referred +to as a <acronym>PO</acronym> (Portable Object) file. +</para> + +<para> +Once all the messages have been translated, the +<acronym>PO</acronym> file is compiled into a machine-readable binary +format, known as a <acronym>MO</acronym> (Machine Object) file. These +files, which will be stored with a <literal +role="extension">.mo</literal> extension +(or a <literal role="extension">.gmo</literal> extension to show +that they were processed by &GNU; gettext), act as a database to +minimize the time taken by the applications to look up each translated +message. +</para> + +<para> This suggests a question: do I need to know what is +inside a <acronym>PO</acronym> file even though I have &kbabel;? The +answer is, undoubtedly, yes. There are situations when a message +catalog can become corrupted and needs to be manually fixed. Most of +these problems are the so-hated <acronym>CVS</acronym> or <acronym>SVN</acronym> conflicts which +occur when a translating process is coordinated by a version management +system, like <acronym>CVS</acronym> or Subversion (<acronym>SVN</acronym>). +&kbabel; cannot help you much if a problem like this arises so a +text editor and some knowledge of <acronym>PO</acronym>-files are +needed. Let's see how a <acronym>PO</acronym> file is made.</para> + +<para><acronym>PO</acronym> files consist of pairs of messages—a +<emphasis>msgid</emphasis> and a <emphasis>msgstr</emphasis>. The +msgid is the text in English and the msgstr is the text translated +into the appropriate language. The text that accompanies each msgid +and msgstr is enclosed within C-like double quotes. An example, taken +from a <acronym>PO</acronym> file for &noatun;, is <literal>msgid +"Open a Playlist"</literal> </para> + +<!-- ### TODO: we would need an example of an entry --> + +<para>Empty lines and those starting with <literal>#</literal> are +ignored. Lines starting with a # represent comments and are a useful +way of providing a note detailing which file this message is going +to be used in and, in the case of the application writers, to provide +additional comments to help translation. &kbabel; displays these +comment lines for every message.</para> + +<para>In many cases the first msgid-msgstr pair in +<acronym>PO</acronym> file is a fake entry (acting as +<acronym>PO</acronym> file header) that contains various information +about the translated <acronym>PO</acronym> file, such as the +application name, translating date, translator name and so on.</para> + +<para> +An useful feature is called <emphasis>plural forms</emphasis>. +English uses only singular and one plural form of nouns, ⪚ <quote>1 file +</quote> and <quote>10 files</quote>. This leads many developers +to an idea that the world is that simple and they can use messages like +<quote>Do you want to delete %1 file(s)?</quote>, where +<literal>%1</literal> denotes a number of files to be deleted. +But this is fundamentally wrong and for many languages such a kind of translation +will not work. For Slovak translation you need 3 different +forms of the message. This number is different for different languages +and even when it is the same, ⪚ Czech uses 3 forms as well, the rule to decide which +form to use can be very different. Plural forms in <acronym>PO</acronym> files are here to help. +</para> + +<note><para> +&kde; developers have chosen a different implementation for the plural forms than +<application>&GNU; gettext</application> and they have introduced their own +format and handling for them. +It is planned to use &GNU; gettext's plural forms in &kde; version 4. +</para></note> + +</sect1> + +<sect1 id="using-editor"> +<title>Editor</title> + +<para>Here is a screenshot of &kbabel;.</para> + +<screenshot> +<screeninfo>Screenshot of &kbabel;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="snap1.png" format="PNG"/> +</imageobject> +<textobject><phrase>Screenshot of &kbabel;</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +For convenience &kbabel; has +toolbars to speed up many operations and, for busy users, there are +many keyboard shortcuts. The main window is divided into four +parts. +</para> + +<para>The <emphasis>upper-left</emphasis> edit box is read-only and +contains the current msgid field from the opened PO-file and its +English text.</para> + +<para>The <emphasis>bottom-left</emphasis> edit box contains the +msgstr field related to the msgid shown and here you can edit the +translated text.</para> + +<para>The <emphasis>top-right</emphasis> part of the window is a comments +panel where you can view the comments added for entry currently being +edited.</para> + +<para>It can be used:</para> + +<itemizedlist> +<listitem><para> +to find out how the current message is treated by the +application (c-formatted or simple) +</para></listitem> +<listitem><para> +in some cases, to read helpful comments added by the application's +developer to assist the translators in their work—for example, +there may be technical hints (used to great effect in the +<application>LyX</application> project) +</para></listitem> +<listitem><para> +when you need to know which file a message is from because you +want to report a spelling mistake in the original English string. +</para></listitem> +</itemizedlist> + +<para> +The editor window (in the bottom right) is the most sophisticated part +of &kbabel;'s main window. Its size can be +adjusted using the splitter line between it and the comment panel +(the panel in the top right). +The editor window has two tabbed panels—one storing search +information, the other context information. The context information +tab contain a scrolled view which shows the previous and next 4 entries +associated with the current entry—essentially it's a small +'snapshot' of the PO file. While translating, it is very common for +message strings to be related to subsequent and previous messages, +so the context panel is useful for looking at the nearby messages to +get a hint as to how the current message can best be +translated. Dialog interface translation is a good example, or widgets +with their associated text and "what's this" message. +</para> + +<sect2 id="more-kbabel-features"> +<title>More &kbabel; Features</title> + +<para> +Each msgid entry can be in three states: +</para> + +<variablelist> + <varlistentry> + <term>untranslated</term> + <listitem> + <para> + there is no translated text currently associated with the msgstr + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>fuzzy</term> + <listitem> + <para> + <command>msgmerge</command> has tried to match a translated + string by looking in rest of PO-file entries. This does not work + perfectly and you must edit the translated text to fit the current + English text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>translated</term> + <listitem> + <para> + the msgid is the completed translated form of the msgstr + </para> + </listitem> + </varlistentry> +</variablelist> + +<para>The state of the current entry is indicated by two +<acronym>LED</acronym>s. Depending on your configuration these can +either be in the status bar or above the <guilabel>translated +string</guilabel> edit box. Both have a customizable color (to +reflect your visual requirements or taste). Please read the <link +linkend="preferences">Preferences</link> section to see how you can +adjust these settings.</para> + +</sect2> + +</sect1> + +<sect1 id="kbabel-features"> +<title>Advanced Translation</title> + +<para> +Now you have an idea how to translate a PO-file. In this section we will follow the standard way +of translating a new PO-file using the advanced features of &kbabel;. We assume you have already +opened a template POT-file and saved it as a PO file. +</para> + +<sect2 id="kbabel-navigation"> +<title>Navigation in PO-file</title> +<para>&kbabel; allows you to easily navigate through the file according to the state of their +translation. The untranslated/fuzzy status was introduced already. A message can be marked as erroneous +as a result of <link linkend="kbabel-validation">validation checking</link> or validation done by <command>msgfmt</command>. +And, of course, &kbabel; supports browsing the history of visited messages with +<guilabel>Forward</guilabel>/<guilabel>Back</guilabel>, like in &konqueror;.</para> +<para> +All commands for navigation are in <menuchoice><guimenu>Go</guimenu></menuchoice> menu. +</para> +<informaltable> +<tgroup cols="2"> +<tbody> + +<row> +<entry><para><keycombo action="simul"><keycap>Page Up</keycap></keycombo></para></entry> +<entry><para>Move to the previous message </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Page Down</keycap></keycombo></para></entry> +<entry><para> Move to the next message</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>Page Up</keycap></keycombo></para></entry> +<entry><para>Move to the previous fuzzy message</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>Page Down</keycap></keycombo></para></entry> +<entry><para>Move to the next fuzzy message</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Alt;<keycap>Page Up</keycap></keycombo></para></entry> +<entry><para>Move to the previous untranslated message</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Alt;<keycap>Page Down</keycap></keycombo></para></entry> +<entry><para>Move to the next untranslated message</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Page Up</keycap></keycombo></para></entry> +<entry><para>Move to the previous error message</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Page Down</keycap></keycombo></para></entry> +<entry><para>Move to the next error message</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;&Shift;<keycap>Page Up</keycap></keycombo></para></entry> +<entry><para>Move to the previous fuzzy or untranslated message</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;&Shift;<keycap>Page Down</keycap></keycombo></para></entry> +<entry><para>Move to the next fuzzy or untranslated message</para></entry> +</row> +</tbody> +</tgroup> +</informaltable> +</sect2> + +<sect2 id="kbabel-cleveredit"> +<title>Clever editing</title> +<para><emphasis>Clever editing</emphasis> means that the editor will help you +easily edit the translation while taking into account specials of the PO format. +It will correctly <quote>escape</quote> as necessary.</para> +<para> +It also supports more than +one mode for inserting end of the line. This is very useful because of the way +gettext handles end of the lines. It simply ignores them. (You can imagine that +all the text in <acronym>msgstr</acronym> is a single line.) If you want insert a <quote>real</quote> end of the +line, you need to insert <userinput>\n</userinput>. But most of translators +do not realize, that a new line in <acronym>msgstr</acronym> does not +add any space between the lines. This can be easily solved by adding a space +at the end of every line. But you can easily forget, so clever editing does this automatically +for you. +</para> +<para>The table below summarizes clever editing features. +</para> + +<informaltable> +<tgroup cols="2"> +<tbody> +<row> +<entry><para><keycombo action="simul"><keycap>Tab</keycap></keycombo></para></entry> +<entry><para>Insert <emphasis>\t</emphasis></para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>"</keycap></keycombo></para></entry> +<entry><para>Insert <emphasis>\"</emphasis></para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Enter</keycap></keycombo></para></entry> +<entry><para>If the last character before cursor is not a space, insert one space. +Then start a new line.</para></entry> +</row><row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>Enter</keycap></keycombo></para></entry> +<entry><para>Start a new line without any additional logic</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Enter</keycap></keycombo></para></entry> +<entry><para>Insert <emphasis>\n</emphasis> and start a new line</para></entry> +</row> +</tbody> +</tgroup> +</informaltable> +<note> +<para> +If you want to see where spaces are, you can turn on <guibutton>Highlight background</guibutton> +and/or <guibutton>Mark whitespaces with points</guibutton> in preferences dialog +on tab <guilabel>Edit</guilabel> <guilabel>Appearance</guilabel>. +</para> +</note> +</sect2> + +<sect2 id="kbabel-roughtranslation"> +<title>Automatic translation</title> +<para>As the first step when starting a new translation, &kbabel; provides a function +for automatic filling of the messages translations by the older translations. Choose +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Rough Translation</guimenuitem> +</menuchoice> +and &kbabel; will present the following dialog: +</para> +<para> +<screenshot> +<screeninfo>Rough translation dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="roughtranslation.png" format="PNG"/> +</imageobject> +</mediaobject> +</screenshot> +</para> +<para> +In the dialog, you should specify what to translate and choose the sources for +the old translations. +</para> +<para> +At the top of the <guilabel>What to translate</guilabel> frame are three +checkboxes (<guilabel>Untranslated entries</guilabel>, <guilabel>Fuzzy entries +</guilabel>, <guilabel>Translated entries</guilabel>) for specifying the kind of +messages you want to translate. Untranslated and fuzzy entries are natural +choices for automatic translation, but you can change already translated +messages as well. +</para> +<para> +The exact matching for <acronym>msgid</acronym>s will always be used for +rough translation. However, you can add more strategies, &ie; +<guilabel>Allow fuzzy translation (slow)</guilabel> and +<guilabel>Allow single word translation</guilabel>. Both of these +additional strategies must be supported by the sources used (see below). +There is no specification, what does <quote>fuzzy translation</quote> mean, +but the purpose is quite obvious. <quote>Single word translation</quote> +is suitable for only some of the languages. &kbabel; will try to translate +each word in <acronym>msgid</acronym> separately and then +put the translated words (or phrases) in the same order in <acronym>msgstr +</acronym>. +</para> +<para> +As a source for rough translation, any dictionary module available can be +used. There is a list of <guilabel>Don't use</guilabel> modules and +<guilabel>Use</guilabel> modules. Modules are used in the order +in the <guilabel>Use</guilabel> list. First module is asked for +translation. If it is not found, next module in the list is asked and so on. +You can use the buttons with arrows for moving modules between the +lists. Don't forget to change the order to suit your needs by <guibutton>Move Up +</guibutton> and <guibutton>Move Down</guibutton> buttons. +</para> +<para> +Normally &kbabel; will mark every roughly translated message as +fuzzy, because it assumes that any automatic translation needs to +be reviewed by a translator. If you are 100% sure that the automatic +translation will be correct, or you will review all the translation anyway. +<guilabel>Mark changed entries as fuzzy</guilabel> allows you to +turn off this automatic fuzzy marking, but you will need to confirm this. +</para> +<para> +If you have set all the options to suit your needs, push <guibutton>Start +</guibutton> to automatically translate messages. You can follow the +progress bar and in case, there is always the <guibutton>Stop</guibutton> +button. +</para> +</sect2> + +<sect2 id="kbabel-validation"> +<title>Validate your translation</title> +<para>Everyone makes mistakes. So &kbabel; supports a number +of checks for typical problems in translations. These checks (not +syntax check) can be basically performed in two ways.</para> +<para> +Checks can be done at each change of the translated text. These +are called <emphasis>automatic</emphasis> checks and they can +be turned on in <link linkend="preferences-editor">the &kbabel; configuration dialog</link>. +Automatic checking of syntax is possible at each saving of the file. +</para> +<para> +The automatic checks can slow down &kbabel;. If you have a slower +computer, you can turn off the automatic checks and use only the +second possibility. You can invoke every kind of check from the +<menuchoice><guimenu>Tools</guimenu><guisubmenu> +Validation</guisubmenu></menuchoice>. Then the check is +performed for all messages in the file and faulty ones are marked as errors. +</para> +<variablelist> + <varlistentry> + <term><guimenuitem>Check Syntax</guimenuitem></term> + <listitem> + <para> + This invokes <command>msgfmt</command> to check validity of the PO file + as seen by &GNU; gettext package. It will show the result of the command + and mark error <acronym>msgstr</acronym>s. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Check Arguments</guimenuitem></term> + <listitem> + <para> + Incorrect translations can crash the application. The most dangerous + parts of translation are arguments, ⪚ for printf-like functions. This check + compares the number and types of the arguments in <acronym>msgid</acronym> + and <acronym>msgstr</acronym>. They must match. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Check Accelerators</guimenuitem></term> + <listitem> + <para> + &GUI; text commonly contain accelerators, &ie; letters which can be used + for fast access to &GUI; elements by keyboard. They are denoted by + special character, ⪚ & in &kde;. Typical requirement of the + translation is that translated text should contain accelerator as well. + This check will notice this problem for you. The accelerator character + can be specified in <guilabel>Preferences</guilabel> on <guilabel>Misc</guilabel> tab. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Look for Translated Context Info</guimenuitem></term> + <listitem> + <para> + You will probably need this only for &kde; translation. Some of the text are too common + and they need to be translated differently in different contexts. In &kde; the context + is described at the beginning of <acronym>msgid</acronym> after the special sequence + <userinput>:_</userinput>. But if some translators are not aware of this convention + and they try to translate context information as well. This check will try to find these. + If the check founds translated context information, you should remove it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Check Plural Forms</guimenuitem></term> + <listitem> + <para> + If the <acronym>msgid</acronym> is specified as a <quote>plural form</quote>, + the translation has to contain the correct number of translations separated by + <userinput>\n</userinput>. The correct number depends on the language of + translation and is specified on <guilabel>Identity</guilabel> tab in <guilabel> + Preferences</guilabel> dialog. This is implemented only for &kde; at the moment. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Check Equations</guimenuitem></term> + <listitem> + <para> + Equations are special format of <acronym>msgid</acronym> typically + used in <filename>.desktop</filename> files. + And because your translations will be merged back to these files, <acronym>msgstr</acronym> + must use this special format as well. This means that the translation must start (up to the + first occurrence of <literal>=</literal> with the same text as the original message, ⪚ + <userinput>Name=</userinput>. + <!-- ### TODO: is this feature is specific to KDE too? How does e.g. GNOME translate them? --> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="kbabel-spellcheck"> +<title>Spellchecking the translation</title> +<para>As always, it is very important to spell-check your translation before +using your result. This way you can find typos and other problems in your translation. +&kbabel; uses the standard &kde; library for spellchecking and its standard +settings can be found in <link linkend="preferences-project-spellcheck">the project setting dialog</link>. Spell checking itself can be found in +<menuchoice><guimenu>Tools</guimenu><guisubmenu>Spelling</guisubmenu> +</menuchoice> submenu. +You can use a number of modes for spell checking: +</para> +<variablelist> + <varlistentry> + <term><guimenuitem>Spell check...</guimenuitem></term> + <listitem> + <para> + This is a generic invocation of a dialog where you can choose + the spellchecking mode and set the default mode. This is + invoked by pressing <keycombo action="simul">&Ctrl;<keycap>I</keycap> + </keycombo>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Check All...</guimenuitem></term> + <listitem> + <para> + Spellcheck all messages in the file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Check from Cursor Position...</guimenuitem></term> + <listitem> + <para> + Start spellchecking at the position in the current message and + progress towards the end of the file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Check Current...</guimenuitem></term> + <listitem> + <para> + Spellcheck the current message only. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guimenuitem>Check Selected Text...</guimenuitem></term> + <listitem> + <para> + If there is a selected text in <acronym>msgstr</acronym> editor, + this option is available and will spellcheck this text only. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="kbabel-tags"> +<title>Translating &XML;, <acronym>HTML</acronym>, ...</title> +<para> +Markup languages are used more and more in &GUI;. +&kde; project also uses <acronym>PO</acronym>-files for translating +DocBook documentation files (which is also a markup language). &kbabel; +contains quite a lot of functionality to support this trend. +</para> +<note> +<para> +Here, we will describe only functions related to tags used for markup itself. The +other problem introduced by using markup languages is translation of +longer texts. This issue is addressed by the <emphasis>diff</emphasis> +feature described in <link linkend="kbabel-diff">the following section</link>. +</para> +</note> +<para> +The current version of &kbabel; is capable to find out which tags are +used in <acronym>msgid</acronym> and provide an easy access to +them using following actions from the <guimenu>Edit</guimenu>: +</para> + +<variablelist> +<varlistentry> + <term> + <guimenuitem>Insert Next Tag</guimenuitem> + </term> + <listitem> + <para> + <action> + This inserts next tag found in msgid to the translation. &kbabel; finds + the tag to be inserted by counting the number of tags from the + beginning of the translation. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guisubmenu>Insert Tag</guisubmenu> + </menuchoice> + </term> + <listitem> + <para> + <action> + This submenu contains all different markup tags found in original english string. + By selecting a tag you can insert it at the current position of cursor in translated text. + translation. + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="kbabel-diff"> +<title>Showing the difference</title> +<para> +As explained already, current applications, trying to be user friendly, contain a lot of +longer descriptive texts, including markup. If a developer changes +a part of the text, the &GNU; gettext system will, in the best case, retain the old +translation and mark it as fuzzy. (In the worst case you will lose the translation +completely, depending on the size of the text changes). This works OK, if +a <acronym>msgid</acronym> is short, because then you can find +the changes quickly. But if the text is long enough, you will struggle to find out +what has been changed (For example, it can be only an article change by proof-reading team.) +</para> +<para> +To help, &kbabel; can be asked to lookup the original <acronym>msgid</acronym> +and to show the difference. The changes are graphically displayed in +the <guilabel>Original String</guilabel> window. The exact method can +be set in the <link linkend="preferences-editor-appearance">&kbabel; +configuration dialog</link>. <menuchoice><guimenu>Tools</guimenu> +<guisubmenu>Diff</guisubmenu> <guimenuitem>Show Diff</guimenuitem> +</menuchoice> will show the differences found. To see the current text +without the mixture of original text and differences, use <menuchoice><guimenu>Tools</guimenu> +<guisubmenu>Diff</guisubmenu> <guimenuitem>Show Original Text</guimenuitem> +</menuchoice>. +</para> +<para> +You can turn automatic lookup of difference on and off by choosing +<menuchoice><guimenu>Tools</guimenu> +<guisubmenu>Diff</guisubmenu> <guimenuitem>Diff Mode</guimenuitem> +</menuchoice>. When the diff mode is on, difference searching starts when you +go to another message. +</para> +<para> +As always, you can use different sources for finding the old version of the +text, all being set in in <link linkend="preferences-diffmode">&kbabel; configuration dialog</link>: +</para> +<variablelist> + <varlistentry> + <term>Translation Database</term> + <listitem> + <para> + You can use Translation Database for difference lookup. + We strongly recommend to turn on the automatic storing of the newly translated messages + into Translation Database in <link linkend="database-fill"> + Translation Database configuration dialog</link>. + This mode can be turned on by <guilabel>Use messages from Translation + Database</guilabel>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Tree of the old files</term> + <listitem> + <para> + This will be used only if searching in Translation Database is turned off. + By setting <guilabel>Base folder for diff files</guilabel> you can + navigate &kbabel;, which file to use for difference. + It takes the relative path of the opened file and uses this relative + path in the folder specified here. If there is a corresponding file, it will + be used. To use this mode, you should make a copy of + old files before each update. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Manually chosen file</term> + <listitem> + <para> + If the previous possibility does not work, correctly, you can always + set the difference file manually by choosing <menuchoice> + <guimenu>Tools</guimenu><guisubmenu>Diff</guisubmenu> + <guimenuitem>Open File for Diff</guimenuitem></menuchoice>. + </para> + </listitem> + </varlistentry> +</variablelist> +<note> +<para> +The difference lookup is not always accurate, because the +<acronym>PO</acronym>-file does not contain any reference to the original +message. +</para> +</note> +</sect2> + +</sect1> + +<sect1 id="kbabel-pluralforms"> +<title>Plural Forms</title> +<para> +Because plural forms are quite a complicated issue, we devote a special section +for their support in &kbabel;. +</para> + +<note><para> +This section handles about &kde; plural forms (to be precise of &kde; version 3). +From &kbabel; version 1.11 (KDE 3.5) on, &kbabel; should be able to +read, edit and save the &GNU; gettext plural forms too. +</para></note> + +<para> +Every language to which &kde; is translated must have set a correct +number of plural forms. This is done by translating a specific entry in <filename>kdelibs.po</filename>. +The number is set by selecting the name of a language, which uses +the same number and <emphasis>rules</emphasis> for finding the +right plural form. The up-to-date list of possible values can be found in the +kdelibs source code, in the file <filename>kdecore/klocale.cpp</filename>. +</para> + +<note><para> +&GNU; gettext allows to define the number and type of plural forms by a formula and to set this +formula independently for each PO file. &kde; can only define the number and type of plural forms +one time in kdelibs. +</para></note> + +<para> +&kde; plural forms are denoted by comment <userinput>_n:</userinput> (including a trailing space) containing +the <literal>%n</literal> argument. This argument is then used in the message +itself and it controls which plural form of your language should be used +depending on the rules for your language. +</para> +<para> +The translation of a plural form message has to have a special format. +It must contain the correct number of translations (one for each plural form) +separated by an end of the line <literal>\n</literal>, +<emphasis>without</emphasis> any <userinput>_n:</userinput> sequence (without the space either). For example, +<quote>_n: Selected 1 file\nSelected %n files</quote> translated to Slovak would be: +</para> +<programlisting> +Vybraný %n súbor\n +Vybrané %n súbory\n +Vybraných %n súborov +</programlisting> +<para> +To check if your translation contains the correct number of +plural forms, use the <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Validation +</guisubmenu> <guimenuitem>Check Plural Forms (KDE only)</guimenuitem> +</menuchoice> menu. +</para> +</sect1> +</chapter> + +<!-- +Local Variables: +mode: xml +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/kbugbuster/Makefile.am b/doc/kbugbuster/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kbugbuster/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kbugbuster/index.docbook b/doc/kbugbuster/index.docbook new file mode 100644 index 00000000..ed3acbb9 --- /dev/null +++ b/doc/kbugbuster/index.docbook @@ -0,0 +1,78 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kbugbuster;"> + <!ENTITY package "kdesdk"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kbugbuster; Handbook</title> + +<authorgroup> +<author> +<firstname></firstname> +<othername></othername> +<surname></surname> +<affiliation> +<address><email></email></address> +</affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<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 (DD/MM/YYYY) and of the version +(Major.minor.lesser), it could be used by automation scripts --> + +<date>2002-03-31</date> +<releaseinfo>0.00.00</releaseinfo> + +<!-- Abstract about this handbook --> + +<abstract> +<para> +&kbugbuster; is part of the kdesdk package. +</para> +</abstract> + + +<keywordset> +<keyword>KDE</keyword> +<keyword>kbugbuster</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> <title>Introduction</title> <para> +The documentation for &kappname; was not finished when &kde; was installed on +this computer.</para> <para>If you need help, please check <ulink +url="http://www.kde.org">The &kde; Website</ulink> for updates, or by +submitting your question to <ulink url="mailto:kde@kde.org">The +&kde; User Mailing list</ulink>.</para> <para><emphasis>The &kde; +Team</emphasis></para> + +&underFDL; + +</chapter> + +&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:ts=2:sw=2:tw=78:noet +--> diff --git a/doc/kcachegrind/Makefile.am b/doc/kcachegrind/Makefile.am new file mode 100644 index 00000000..e748f2a2 --- /dev/null +++ b/doc/kcachegrind/Makefile.am @@ -0,0 +1,4 @@ +KDE_LANG = en +KDE_DOCS = AUTO + + diff --git a/doc/kcachegrind/index.docbook b/doc/kcachegrind/index.docbook new file mode 100644 index 00000000..31cf322c --- /dev/null +++ b/doc/kcachegrind/index.docbook @@ -0,0 +1,962 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kcachegrind '<application>KCachegrind</application>'> + <!ENTITY cachegrind "<application>Cachegrind</application>"> + <!ENTITY calltree "<application>Calltree</application>"> + <!ENTITY callgrind "<application>Callgrind</application>"> + <!ENTITY valgrind "<application>Valgrind</application>"> + <!ENTITY oprofile "<application>OProfile</application>"> + <!ENTITY kappname "&kcachegrind;"> + <!ENTITY package "kdesdk"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<!-- ................................................................ --> + +<book lang="&language;"> + +<bookinfo> +<title>The &kcachegrind; Handbook</title> + +<authorgroup> +<author> +<firstname>Josef</firstname> +<surname>Weidendorfer</surname> +<affiliation> +<address><email>Josef.Weidendorfer@gmx.de</email></address> +</affiliation> +</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2002-2004</year> +<holder>Josef Weidendorfer</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<date>2004-07-27</date> +<releaseinfo>0.4.6</releaseinfo> + +<abstract> +<para> +&kcachegrind; is a profile data visualization tool, written using the &kde; environment. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdesdk</keyword> +<keyword>Cachegrind</keyword> +<keyword>Callgrind</keyword> +<keyword>Valgrind</keyword> +<keyword>Profiling</keyword> +</keywordset> + +</bookinfo> + + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&kappname; is a browser for data produced by profiling tools. +This chapter explains what profiling is for, how it is done, and +gives some examples of profiling tools available. +</para> + +<sect1 id="introduction-profiling"> +<title>Profiling</title> + +<para> +When developing a program, one of the last steps often involves +performance optimizations. As it makes no sense to optimize +functions rarely used, because that would be a waste +of time, one needs to know in +which part of a program most of the time is spent. +</para> + +<para> +For sequential code, collecting statistical data of the programs +runtime characteristic like time +numbers spent in functions and code lines usually is enough. +This is called Profiling. The program is run under control of a profiling tool, which gives the summary of an execution run at the end. +In contrast, for parallel code, performance problems typically are caused when one processor is waiting for data from another. As this waiting time usually can not easily attributed, here it is better to generate timestamped event traces. KCachegrind can not visualize this kind of data. +</para> + +<para> +After analyzing the produced profile data, it should be easy +to see the hot spots and bottlenecks of the code: for example, assumptions +about call counts can be checked, and identified code regions can be optimized. +Afterwards, the success of the optimization should be verified with another profile run. +</para> +</sect1> + +<sect1 id="introduction-methods"> +<title>Profiling Methods</title> + +<para>To exactly measure the time passed or record the events happening during the execution of a code region (e.g. a function), additional measurement code needs to be inserted before and after the given region. This code reads the time, or a global event count, and calculates differences. Thus, the original code has to be changed before execution. This is called instrumentation. Instrumentation can be done by the programmer itself, the compiler, or by the runtime system. As interesting regions usually are nested, the overhead of measurement always influences the measurement itself. Thus, instrumentation should be done selectively and results have to be interpreted with care. Of course, this makes performance analysis by exact measurement a very complex process.</para> + +<para>Exact measurement is possible because of hardware counters (including counters incrementing on a time tick) provided in modern processors, which are incremented whenever an event is happening. As we want to attribute events to code regions, without the counters, we would have to handle every event by incrementing a counter for the current code region ourself. Doing this in software is, of course, not possible; but, on the assumption that the event distribution over source code is similar when looking only at every n-th event instead of every event, a measurement method whose overhead is tunable has been developed: it is called Sampling. Time Based Sampling (TBS) uses a timer to regularly look at the program counter to create a histogram over the program code. Event Based Sampling (EBS) exploits the hardware counters of modern processors, and uses a mode where an interrupt handler is called on counter underflow to generate a histogram of the corresponding event distribution: in the handler, the event counter is always reinitialized to the 'n' of the sampling method. The advantage of sampling +is that the code does not have to be changed, but it is still a compromise: the above assumption will be more correct if n is small, but the smaller the n, the higher the overhead of the interrupt handler.</para> + +<para>Another measurement method is to simulate things happening in the computer system when executing a given code, i.e. execution driven simulation. The simulation is always derived from a more or less accurate machine model; however, with very detailed machine models, giving very close approximations to reality, the simulation time can be unacceptably high in practice. The advantage of simulation is that arbitrarily complex measurement/simulation code can be inserted in a given code without perturbing results. Doing this directly before execution (called runtime instrumentation), using the original binary, is very comfortable for the user: no re-compilation is necessary. Simulation becomes usable when simulating only parts of a machine with a simple model; another advantage is that the results produced by simple models are often easier to understand: often, the problem with real hardware is that results include overlapping effects from different parts of the machine.</para> +</sect1> + +<sect1 id="introduction-tools"> +<title>Profiling Tools</title> + +<para> +Most known is the GCC profiling tool <application>gprof</application>: +One needs to compile the program with option <option>-pg</option>; +running the program generates a file <filename>gmon.out</filename>, +which can be transformed into human-readable form with +<command>gprof</command>. One disadvantage is the needed re-compilation +step to prepare the executable, which has to be statically linked. +The method used here is compiler-generated instrumention - which measures call arcs happening among functions and corresponding call counts - in conjunction with TBS - which gives a histogram of time distribution over the code. Using both pieces of information, it is possible to heuristically calculate inclusive time of functions, i.e. time spent in a function together with all functions called from it. +</para> + +<para>For exact measurement of events happening, libraries exist with functions able to read out hardware performance counters. Most known here is the PerfCtr patch for Linux, and the architecture independent libraries PAPI and PCL. Still, exact measurement needs instrumentation of code, as stated above. Either one uses the libraries itself or uses automatic instrumentation systems like ADAPTOR (for FORTRAN source instrumentation) or DynaProf (code injection via DynInst).</para> + +<para>&oprofile; is a system-wide profiling tool for Linux using Sampling.</para> + +<para> +In many aspects, a comfortable way of Profiling is using +Cachegrind or Callgrind, which are simulators using the runtime +instrumentation framework &valgrind;. Because there is no need +to access hardware counters (often difficult with today's Linux installations), and binaries to be profiled can be left unmodified, +it is a good alternative to other profiling tools. +The disadvantage of simulation - slowdown - can be reduced by doing the simulation on only the interesting program parts, and perhaps only on a few iterations of a loop. Without measurement/simulation instrumentation, Valgrind's usage only has a slowdown factor in the range of 3 to 5. +Also, when only the call graph and call counts +are of interest, the cache simulator can be switched off. +</para> + +<para> +Cache simulation is the first step in approximating real times; as +,on modern systems, runtime is very sensitive to the exploitation +of so called caches (small and fast buffers which accelerate repeated +accesses to the same main memory cells.) +&cachegrind; does cache simulation by catching +memory accesses. +The data produced +includes the number of instruction/data memory accesses and 1st/2nd +level cache misses, and relates it to source lines and functions of +the run program. By combining these miss counts, using miss latencies from typical processors, an estimation of spent time can be given. +</para> + +<para>Callgrind is an extension of &cachegrind; that +builds up the call graph of a program on-the-fly, +&ie; how the functions call each other and how many events happen +while running a function. Also, the profile data to be collected +can separated by threads and call chain contexts. It can provide +profiling data on an instruction level to allow for annotation of +disassembled code. +</para> +</sect1> + +<sect1 id="introduction-visualization"> +<title>Visualization</title> + +<para> +Profiling tools typically produce a large amount of data. The wish +to easily browse down and up the call graph, together with fast switching of the sorting mode of functions and display of different event types, motivates a GUI application to accomplish this task. +</para> + +<para> +&kappname; is an visualization for profile data fulfilling these wishes. Despite being programmed first with browsing the data from &cachegrind; and &calltree; in mind, there are converters available to be able to display profile data produced by other tools. In the appendix, a description of the Cachegrind/Callgrind file format is given. +</para> + +<para> +Besides a list of functions sorted according exclusive or inclusive cost metrics, and optionally grouped by source file, shared library or C++ class, +&kappname; features various visualization views for a selected function, namely + +<itemizedlist> +<listitem><para>a call-graph view, which shows a section of the call graph around the selected function,</para> +</listitem> +<listitem><para>a tree-map view, which allows nested-call relations to be visualized, together with inclusive cost metric for fast visual detection of problematic functions,</para> +</listitem> +<listitem><para>source code and disassembler annotation views, allowing to see details of cost related to source lines and assembler instructions.</para> +</listitem> +</itemizedlist> + +</para> +</sect1> +</chapter> + +<chapter id="using-kcachegrind"> +<title>Using &kcachegrind;</title> + +<sect1 id="using-profile"> +<title>Generate Data to Visualize</title> + +<para>First, one wants to generate performance data by measuring aspects of the +runtime characteristics of an application, using a profiling tool. &kcachegrind; +itself does not include any profiling tool, but is good in being used together with +&callgrind;, and by using a converter, also can be used to visualize data produced +with &oprofile;. Although the scope of this manual is not to document profiling +with these tools, the next section provides short quickstart tutorials to get you started. +</para> + +<sect2> +<title>&callgrind;</title> + +<para> +&callgrind; is available from +<ulink url="http://kcachegrind.sf.net"> +http://kcachegrind.sf.net</ulink>. +Note that it previously was called &calltree;, but that name was misleading. +</para> + +<para> +Most common use is to prefix the command line to start your application with +<application>callgrind</application>, like in + +<blockquote><para><command>callgrind myprogram myargs</command></para></blockquote> + +At program termination, a file <filename>callgrind.out.pid</filename> will be +generated which can be loaded into &kcachegrind;. +</para> + +<para> +More advanced use is to dump out profile data whenever a given function of +your application is called. E.g. for <command>konqueror</command>, +to see profile data only +for rendering a web page, you could decide to dump the data whenever you +select the menu item View/Reload. This corresponds to a call to +<symbol>KonqMainWindow::slotReload</symbol>. Use + +<blockquote><para><command> +callgrind --dump-before=KonqMainWindow::slotReload konqueror </command></para></blockquote> + +This will produce multiple profile data files with an additional +sequential number at the end of the filename. A file without such an +number at the end (only ending in the process PID) will also be produced; +by loading this file into &kcachegrind;, all others are loaded too, and can +be seen in the Parts Overview and Parts list. +</para> + +</sect2> + +<sect2> +<title>&oprofile;</title> + +<para> +&oprofile; is available from +<ulink url="http://oprofile.sf.net"> +http://oprofile.sf.net</ulink>. Follow the installation instructions on the web site; +but, before you do, check if your distribution does not already provide it as package (like SuSE). +</para> + +<para> +System-wide profiling is only permitted to the root user, +as all actions on the system can be observed; therefore, the following has to be done as root. +First, configure the profiling process, using the GUI <command>oprof_start</command> or the +command-line tool opcontrol. Standard configuration should be timer mode (TBS, see introduction). To start the measurement, run +<command>opcontrol -s</command>. Then run the application you are interested in and, afterwards, do a <command>opcontrol -d</command>. This will write out +the measurement results into files under directory <filename>/var/lib/oprofile/samples/</filename>. To be able to visualize the data in &kcachegrind;, do in an empty directory: + +<blockquote><para><command> +opreport -gdf | op2callgrind +</command></para></blockquote> + +This will produce a lot of files, one for every program which was running +on the system. Each one can be loaded into &kcachegrind; on its own. +</para> + +</sect2> +</sect1> + +<sect1 id="using-basics"> +<title>User Interface Basics</title> + +<para> +When starting &kcachegrind; with a profile data file as argument, or after loading one with File/Open, you will see a sidebar containing the function list +at the left; and, on the right the main part, an area with visualizations for +a selected function. This visualization area can be arbitrarily configured to +show multiple visualizations at once. +</para> + +<para> +At first start, this area will be +divided into a top and a bottom part, each with different visualizations +selectable by tabs. To move visualization views, use the context menu of +the tabs, and adjust the splitters between visualizations. To quickly switch +between different visualization layouts, use View/Layouts/Duplicate, change +the layout and switch between layouts with View/Layout/Next (or, even better, +use the corresponding keyboard shortcuts). +</para> + +<para> +The active event type is important for visualization: for &callgrind;, this +is, for example, Cache Misses or Cycle Estimation; for &oprofile;, this is "Timer" in the simplest case. You can change the event type via a combobox in the toolbar or in the Event Type view. +A first overview of the runtime characteristics should be given when you select function <symbol>main</symbol> in the left list, and look at the call graph visualization; there, you see calls happening in your program. Note that the call graph view only shows functions with high event count. By double-clicking a function in the graph, it will change to show the called functions around the selected one. +</para> + +<para> +To explore the GUI further, in addition to this manual, also have a look at the documentation section on the web site +<ulink url="http://kcachegrind.sf.net"> +http://kcachegrind.sf.net</ulink>. +Also, +every widget in &kcachegrind; has <quote>What's this</quote> help. +</para> +</sect1> + +</chapter> + + +<chapter id="kcachegrind-concepts"> +<title>Basic Concepts</title> + +<para>This chapter explains some concepts of the &kcachegrind;, and +introduces terms used in the interface. +</para> + +<sect1 id="concepts-model"> +<title>The Data Model for Profile Data</title> + +<sect2> +<title>Cost Entities</title> + +<para> +Cost counts of event types (like L2 Misses) are attributed to cost entities, which are items with relationship to source code or data structures of a given program. Cost entities not only can be simple code or data positions, but also position tuples. For example, a call has a source and a target, or a data address can have a data type and an code position where its allocation happened. +</para> + +<para> +The cost entities known to KCachegrind are given in the following. +Simple Positions: +<itemizedlist> +<listitem><para> +Instruction. An assembler instruction at a specified address. +</para></listitem> +<listitem><para> +Source Line of a Function. +All instructions that the compiler (via debug information) maps to a given source line specified by source file name and line number, and which are executed in the context of some function. The latter is needed because a source line inside of an inlined function can appear in the context of multiple functions. Instructions without any mapping to an actual source line are mapped to line number 0 in file "???". +</para></listitem> +<listitem><para> +Function. +All source lines of a given function make up the function itself. A function is specified by its name and its location in some binary object if available. The latter is needed because binary objects of a single program each can hold functions with the same name (these can be accessed e.g. with dlopen/dlsym; the runtime linker resolves functions in a given search order of binary objects used). If a profiling tool can not detect the symbol name of a function, e.g. because debug information is not available, either the address of the first executed instruction typically is used, or "???". +</para></listitem> +<listitem><para> +Binary Object. +All functions whose code is inside the range of a given binary object, either the main executable or a shared library. +</para></listitem> +<listitem><para> +Source File. +All functions whose first instruction is mapped to a line of the given source file. +</para></listitem> +<listitem><para> +Class. +Symbol names of functions typically are hierarchically ordered in name spaces, e.g. C++ namespaces, or classes of object oriented languages; thus, a class can hold functions of the class or embedded classes itself. +</para></listitem> +<listitem><para> +Profile Part. +Some time section of a profile run, with a given thread ID, process ID, and command line executed. +</para></listitem> +</itemizedlist> + +As can be seen from the list, a set of cost entities often defines another cost entity; thus, there is a inclusion hierarchy of cost entities which should be obvious from the description above. +</para> + +<para> +Positions tuples: +<itemizedlist> +<listitem><para> +Call from instruction address to target function. +</para></listitem> +<listitem><para> +Call from source line to target function. +</para></listitem> +<listitem><para> +Call from source function to target function. +</para></listitem> +<listitem><para> +(Un)conditional Jump from source to target instruction. +</para></listitem> +<listitem><para> +(Un)conditional Jump from source to target line. +</para></listitem> +</itemizedlist> + +Jumps between functions are not allowed, as this makes no sense in a call graph; thus, constructs like exception handling and long jumps in C have to be translated to popping the call stack as needed. +</para> + +</sect2> + + + +<sect2> +<title>Event Types</title> + +<para> +Arbitrary event types can be specified in the profile data by giving them a name. Their cost related to a cost entity is a 64-bit integer. +</para> +<para> +Event types whose costs are specified in a profile data file are called real events. Additionally, one can specify formulas for event types calculated from real events, which are called inherited events. +</para> +</sect2> + +</sect1> + +<sect1 id="concepts-state"> +<title>Visualization State</title> + +<para> +The Visualization state of a KCachegrind window includes: +<itemizedlist> +<listitem><para> +the primary and secondary event type chosen for display, +</para></listitem> +<listitem><para> +the function grouping (used in the Function Profile list and entity coloring), +</para></listitem> +<listitem><para> +the profile parts whose costs are to be included in visualization, +</para></listitem> +<listitem><para> +an active cost entity (e.g. a function selected from the function profile dockable), +</para></listitem> +<listitem><para> +a selected cost entity. +</para></listitem> +</itemizedlist> + +This state influences visualizations. +</para> +<para> +Visualizations always are shown for one, the active, cost entity. When a given visualization is not appropriate for a cost entity, it is disabled (e.g. when selecting an ELF object in the group list by double-clicking, source annotation for an ELF object make no sense). +</para> +<para> +For example, for an active function, the callee list shows all the functions called from the active one: one can select one of these functions without making it active; also, if the call-graph is shown nearside, it will automatically select the same function. +</para> + +</sect1> + +<sect1 id="concepts-guiparts"> +<title>Parts of the GUI</title> + +<sect2> +<title>Sidedocks</title> +<para> +Sidedocks (Dockables) are side windows which can be placed at any border of an KCachegrind window. They always contain a list of cost entities sorted in some manner. +<itemizedlist> +<listitem><para> +Function Profile. +The Function Profile is a list of functions showing inclusive and exclusive cost, call count, name and position of functions. +</para></listitem> +<listitem><para> +Parts Overview +</para></listitem> +<listitem><para> +Call Stack +</para></listitem> +</itemizedlist> +</para> +</sect2> + +<sect2> +<title>Visualization Area</title> +<para> +The visualization area, typically the right part of a KCachegrind main window, is made up of one (default) or more Tab Views, either lined up horizontally or vertically. Each tab view holds different visualization views of only one cost entity at a time. The name of this entity is given at the top of the tab view. If there are multiple tab views, only one is active. The entity name in the active tab view is shown in bold and determines the active cost entity of the KCachegrind window. +</para> +</sect2> + +<sect2> +<title>Areas of a Tab View</title> +<para> +Each tab view can hold up to four view areas, namely Top, Right, Left, and Bottom. Each area can hold multiple stacked visualization views. The visible view of an area is selected by a tab bar. The tab bars of the top and right area are at the top; the tab bars of the left and bottom area are at the bottom. You can specify which kind of visualization should go into which area by using the context menus of the tabs. +</para> +</sect2> + +<sect2> +<title>Synchronized Visualization via Selected Entity in a Tab View</title> +<para> +Besides an active entity, each tab view has an selected entity. As most visualization types show multiple entities with the active one somehow centered, you can change the selected item by navigating inside a visualization (by clicking with the mouse or using the keyboard). Typically, selected items are shown in an highlighted state. By changing the selected entity in one of the visualizations of a tab view, all other visualizations in the tab view accordingly highlight the new selected entity. +</para> +</sect2> + +<sect2> +<title>Synchronization between Tab Views</title> +<para> +If there are multiple tab views, a selection change in one tab view leads to an activation change in the next (to right/to bottom) tab view. This kind of linkage should, for example, allow for fast browsing in call graphs. +</para> +</sect2> + +<sect2> +<title>Layouts</title> +<para> +The layout of all the tab views of a window can be saved (see menu item View/Layout). After duplicating the current layout (Ctrl+Plus or menu) and changing some sizes or moving a visualization view to another area of an tab view, you can quickly switch between the old and the new layout via Ctrl+Left/Right. The set of layouts will be stored between KCachegrind sessions of the same profiled command. You can make the current set of layouts as the default one for new KCachegrind sessions, or restore to the default layout set. +</para> +</sect2> +</sect1> + +<sect1 id="concepts-sidedocks"> +<title>Sidedocks</title> + +<sect2> +<title>Flat Profile</title> +<para> +The flat profile contains a group list and a function list. The group list contains all groups where cost is spent in, depending on the chosen group type. The group list is hidden when grouping is switched off. +</para> +<para> +The function list contains the functions of the selected group (or all functions if grouping is switched off), ordered by some column, e.g. inclusive or self costs spent therein. There is a maximal number of functions shown in the list, which is configurable in Settings/Configure KCachegrind. +</para> +</sect2> + +<sect2> +<title>Parts Overview</title> +<para> +In a profile run, multiple profile data files can be produced, which can be loaded together into KCachegrind. The Parts Overview dockable shows these, horizontally ordered according creation time; the rectangle sizes are proportional to the cost spent in the parts. You can select one or several parts to constrain the costs shown in the other KCachegrind views to these parts only. +</para> +<para> +The parts are further subdivided: there is a partitioning and an inclusive cost split mode: +<itemizedlist> +<listitem><para> +Partitioning: You see the partitioning into groups for a profile data part, according to the group type selected. For example, if ELF object groups are selected, you see colored rectangles for each used ELF object (shared library or executable), sized according to the cost spent therein. +</para></listitem> +<listitem><para> +Inclusive Cost Split: A rectangle showing the inclusive cost of the current active function in the part is shown. This, again, is split up to show inclusive costs of its callees. +</para></listitem> +</itemizedlist> +</para> +</sect2> + +<sect2> +<title>Call Stack</title> +<para> +This is a purely fictional 'most probable' call stack. It is built up by starting with the current active function and adds the callers/callees with highest cost at the top and to bottom. +</para> +<para> +The 'Cost' and 'Calls' columns show the cost used for all calls from the function in the line above. +</para> +</sect2> +</sect1> + +<sect1 id="concepts-visualizations"> +<title>Visualizations</title> + +<sect2> +<title>Event Types</title> +<para> +This list shows all cost types available and the corresponding self and inclusive cost of the current active function for that event type. +</para> +<para> +By choosing an event type from the list, you change the type of costs shown all over KCachegrind to be the selected one. +</para> +</sect2> + +<sect2> +<title>Call Lists</title> +<para> +These lists show calls to/from the current active function. With ''all' callers/callees functions are meant which can be reached in caller/callee direction, even when other functions are in between. +</para> +<para> +Call list views include: +<itemizedlist> +<listitem><para> +Direct Callers +</para></listitem> +<listitem><para> +Direct Callees +</para></listitem> +<listitem><para> +All Callers +</para></listitem> +<listitem><para> +All Callees +</para></listitem> +</itemizedlist> +</para> +</sect2> + +<sect2> +<title>Maps</title> +<para> +A treemap visualization of the primary event type, up or down the call hierarchy. Each colored rectangle represents a function; its size tries to be proportional to the cost spent therein while the active function is running (however, there are drawing constrains). +</para> +<para> +For the Caller Map, the graph shows the nested hierarchy of all callers of the current activated function; for the Callee Map, it shows the nested hierarchy of all callees of the current activated function. +</para> +<para> +Appearance options can be found in the in the context menu. To get exact size proportions, choose 'Hide incorrect borders'. As this mode can be very time consuming, you may want to limit the maximum drawn nesting level before. 'Best' determinates the split direction for children from the aspect ratio of the parent. 'Always Best' decides on remaining space for each sibling. 'Ignore Proportions' takes space for function name drawing before drawing children. Note that size proportions can get heavily wrong. +</para> +<para> +Keyboard navigation is available with the left/right arrow keys for traversing siblings, and up/down arrow keys to go a nesting level up/down. 'Return' activates the current item. +</para> +</sect2> + +<sect2> +<title>Call Graph</title> +<para> +This view shows the call graph around the active function. +The shown cost is only the cost which is spent while the active function was actually running; i.e. the cost shown for main() - if it's visible - should be the same as the cost of the active function, as that is the part of inclusive cost of main() spent while the active function was running. +</para> +<para> +For cycles, blue call arrows indicate that this is an artificial call added for correct drawing which actually never happened. +</para> +<para> +If the graph is larger than the widget area, a bird's eye view is shown in one edge. There are similar visualization options as for the Call Treemap; the selected function is highlighted. +</para> +</sect2> + +<sect2> +<title>Annotations</title> +<para> +The annotated source/assembler lists show the source lines/disassembled instructions of the current active function together with (self) cost spent while executing the code of a source line/instruction. If there was a call, lines with details on the call are inserted into the source: the (inclusive) cost spent inside of the call, the number of calls happening, and the call destination. +</para> +<para> +Select such a call information line to activate the call destination. +</para> +</sect2> +</sect1> + +</chapter> + + +<chapter id="commands"> +<title>Command Reference</title> + +<sect1 id="kcachegrind-mainwindow"> +<title>The main &kcachegrind; window</title> +<para></para> + +<sect2> +<title>The <guimenu>File</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo>&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>New</guimenuitem> +</menuchoice></term> +<listitem><para><action> +Opens an empty toplevel window into which you can load profile data. +</action> +This action is not really needed, as File/Open will give you a new toplevel window when the current one shows already some data. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo>&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Open</guimenuitem> +</menuchoice></term> +<listitem><para><action> +Pops up the File Open Dialog to choose a profile data file to be loaded. +</action> +If there is some data already shown in the current toplevel window, this will open a new window; if you want to open additional profile data in the current window, use File/Add. +</para> +<para> +The name of profile data files usually ends in ..-, where and are optional and are used for multiple profile data files belonging to one application run. By loading a file ending only in ., eventually existing data files for this run, but with additional endings, are loaded too. +</para> +<para> +Example: If there exist profile data files cachegrind.out.123 and cachegrind.out.123.1, by loading the first, the second will be automatically loaded too. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Add</guimenuitem> +</menuchoice></term> +<listitem><para><action> +Adds a profile data file to the current window. +</action> +Using this, you can force multiple data files to be loaded into the same toplevel window even if they are not from the same run as given by the profile data file naming convention. This can, for example, be used for nearside comparison. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Reload</guimenuitem> +</menuchoice></term> +<listitem><para><action> +Reload the profile data. +</action> +This is most interesting after another profile data file was generated for an already loaded application run. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo>&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para><action>Quits</action> &kappname;</para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect2> + +<sect2> +<title>The <guimenu>View</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Primary Event Type</guimenuitem> +</menuchoice></term> +<listitem><para><action>(To-do)</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Secondary Event Type</guimenuitem> +</menuchoice></term> +<listitem><para><action>(To-do)</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Grouping</guimenuitem> +</menuchoice></term> +<listitem><para><action>(To-do)</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Layout</guimenuitem> +</menuchoice></term> +<listitem><para><action>(To-do)</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Split</guimenuitem> +</menuchoice></term> +<listitem><para><action>(To-do)</action></para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + + +</sect1> +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + +&reporting.bugs; +&updating.documentation; + +<qandaset id="faqlist"> + + +<qandaentry> +<question> +<para> +What is &kcachegrind; for? I have no idea. +</para> +</question> +<answer> +<para> +&kcachegrind; is a helpful at a later stage in software development, +called Profiling. If you don't develop applications, you don't need +&kcachegrind;. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +What is the difference between 'Incl.' and 'Self' ? +</para> +</question> +<answer> +<para>These are cost attributes for functions regarding some event type. As functions can call each other, it makes sense to distinguish the cost of the function itself ('Self Cost') and the cost including all called functions ('Inclusive Cost'). 'Self' is sometimes also referred to as 'Exclusive' costs. +</para> +<para> +So, for example, for main(), you will always have a inclusive cost of almost 100%, whereas the self cost is negligible when the real work is done in another function. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>The toolbar/menubar of my KCachegrind looks so spartanic. Is this normal?</para> +</question> +<answer> +<para> +Obviously KCachegrind is wrongly installed on your system. It is recommended to compile it with the installation prefix to be your system wide KDE base directory like <command>configure --prefix=/opt/kde3; make install</command>. +If you choose another directory like $HOME/kde, you should set the environment variable KDEDIR to this directory before running KCachegrind. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +If I double-click on a function down in the Call Graph View, it shows for the function main the same cost as the selected function. Isn't this supposed to be constant 100% ? +</para> +</question> +<answer> +<para> +You have activated a function below main() with cost less than main(). For any function, only that part of the full cost of the function is shown, that is spent while the activated function is running; that is, the cost shown for any function can never be higher than the cost of the activated function. +</para> +</answer> +</qandaentry> + + +</qandaset> +</chapter> + +<chapter id="glossary"> +<title>Glossary</title> + +<para>The following is a mixed list of terms. + +<itemizedlist> +<listitem><para> +Profiling: The process of collecting statistical information about runtime characteristics of program runs. +</para></listitem> +<listitem><para> +Tracing: The process of supervising a program run and storing events happening sorted by a timestap in a output file, the Trace. +</para></listitem> +<listitem><para> +Trace: A sequence of timestamped events that occurred while tracing a program run. Its size is typically linear to the execution time of the program run. +</para></listitem> +<listitem><para> +Profile Data File: A file containing data measured in a profile experiment (or part of) or produced by postprocessing a trace. Its size is typically linear to the code size of the program. +</para></listitem> +<listitem><para> +Profile Data Part (incorrectly used also: Trace Part): Data from a profile data file. +</para></listitem> +<listitem><para> +Profile Experiment: A program run supervised by a profiling tool, producing possibly multiple profile data files from parts and/or threads of the run. +</para></listitem> +<listitem><para> +Profile Project: A configuration for profile experiments used for one program which has to be profiled, perhaps in multiple versions. Comparisons of profile data typically only makes sense between profile data produced in experiments of one profile project. +</para></listitem> +<listitem><para> +Cost Entity: An abstract item related to source code to which event counts can be attributed. Dimensions for cost entities are code location (e.g. source line, function), data location (e.g. accessed data type, data object), execution location (e.g. thread, process), and tuples or triples of the aforementioned positions (e.g. calls, object access from statement, evicted data from cache). +</para></listitem> +<listitem><para> +Event Type: The kind of event of which costs can be attributed to a cost entity. There exist real event types and inherited event types. +</para></listitem> +<listitem><para> +Real Event Type: A event type that can be measured by a tool. This needs the existence of a sensor for the given event type. +</para></listitem> +<listitem><para> +Inherited Event Type: A virtual event type only visible in the visualization which is defined by a formula to be calculated from real event types. +</para></listitem> +<listitem><para> +Event Costs: Sum of events of some event type occurring while the execution is related to some cost entity. The cost is attributed to the entity. +</para></listitem> +</itemizedlist> +</para> +</chapter> + +<chapter id="credits"> + + +<title>Credits and License</title> + +<para> +&kappname; +</para> +<para> +Thanks to Julian Seward for his excellent &valgrind;, and Nicholas +Nethercote for the &cachegrind; addition. Without these programs, +<application>KCachegrind</application> would not exist. Some ideas +for this &GUI; were from them, too. +</para> +<para> +And thanks for all the bug reports/suggestions from different +users. +</para> + +&underFDL; <!-- FDL License --> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kcachegrind"> +<title>How to obtain &kcachegrind;</title> + +<para> +&kcachegrind; is part of the &package; package of &kde;. For less supported +interim releases, &callgrind; and further documentation, see +the homepage at +<ulink url="http://kcachegrind.sf.net"> +http://kcachegrind.sf.net</ulink>. Look there for +further installation and compile instructions. +</para> +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para> +In order to successfully use &kcachegrind;, you need &kde; 3.x. For +generating profile data, &cachegrind; or &calltree;/&callgrind; is recommend. +</para> +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +</sect1> + +<sect1 id="configuration"> +<title>Configuration</title> + +<para>All configuration options are either in the configuration dialog +or in the context popup menus of the visualizations. +</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: +--> + + + + + + + + + + + + + diff --git a/doc/kompare/Makefile.am b/doc/kompare/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kompare/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kompare/index.docbook b/doc/kompare/index.docbook new file mode 100644 index 00000000..04f30a7f --- /dev/null +++ b/doc/kompare/index.docbook @@ -0,0 +1,910 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kompare;"> + <!ENTITY version "3.4"> + <!ENTITY package "kdesdk"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> + <title>The &kompare; Handbook</title> + + <authorgroup> + +<author><firstname>Sean</firstname><surname>Wheller</surname><email>sean@inwords.co.za</email></author> + <!-- TRANS:ROLES_OF_TRANSLATORS --> + </authorgroup> + +<copyright> +<year>2007</year> +<holder>Sean Wheller</holder> +</copyright> + + <legalnotice>&FDLNotice;</legalnotice> + +<date>2007-01-20</date> +<releaseinfo>3.4</releaseinfo> + +<!-- Abstract about this handbook --> + +<abstract> +<para> +&kompare; is a &GUI; front-end program that enables differences between source files to be viewed and merged. +&kompare; can be used to compare differences on files or the contents of folders. &kompare; supports a variety +of diff formats and provide many options to customize the information level displayed.</para> +<para>This document describes &kompare; version &version;.</para> +</abstract> + + +<keywordset> +<keyword>KDE</keyword> +<keyword>Kompare</keyword> +<keyword>Diff</keyword> +<keyword>Merge</keyword> +<keyword>Patch</keyword> +<keyword>Hunk</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>When two or more people are working on a file and passing it back and forth between one another, it becomes difficult to +see what changes have been made to a new version or copy of the file. Opening the new copy and the original, side-by-side in the +application used to create it is one solution but, laborious, time consuming, and prone to error. This is where a program to show +differences, diffs for short, is useful.</para> + +<para>As would be expected, an appropriate name for such a program would be "diff". As it happens, the program diff is installed on +most &Linux;-based systems and is used for exactly this purpose. Developers often use diff, as a command line tool, to show differences +between versions of a source code file. However, the use of diff is not limited to showing differences in code source files, +it can be used on many text-based file types.</para> + +<para>Using diff from the command line can be confusing, learning the diff command syntax and deciphering the output can bewilder most people. +This is where &kompare; comes into play. Providing a graphical front-end to the diff program, the interface displays source and destination files +side-by-side with all differences automatically highlighted. From this starting point, changes in one file can be sequentially applied to the other file +on a selective and controlled basis. Not all changes need to be applied and if you do apply a change it can always be 'unapplied'. +When all required changes have been applied they can be saved and will display as normal in the original application used to create the file.</para> + +<para>In addition to displaying differences between a source and destination file, &kompare; can be used to create and view a special file called a 'diff'. +This file captures the differences between the two sources into a single file that can be used to view and apply changes to any other copy of the file. +For example, if two people are editing a document. The first person wants to make changes and send just the changes made to the second person. +Normally, the first person would send a complete copy of the modified document to the second person, who would then have to compare the modified document +side-by-side with unmodified version. The process for this is much like what we have described in the previous paragraphs. With &kompare; the first person +would first make a local copy of the file to be modified, then make changes and compare the original and modified copy. Now using &kompare; a diff file +can be created that captures only the changes made. This can be sent to the second person in place of a whole file containing the changes.</para> + +<para>Using &kompare; the second person can view the diff file, compare it to the local copy of the document and apply the changes made by the first person. +So the process can go on for many versions of the document, each person making changes, creating diffs, distributing them and applying them. +This process is commonly called "patching", a term taken from the program named "patch" which is another command line +tool specifically designed for the purpose of applying diff files.</para> + +<para>It sometimes happens that people edit a file at the same time. In this situation it is likely that people will make changes in the document at +exactly the same line. This creates a problem because, without applied caution, people could be overwriting each others work as they apply the diff files they receive. +Fortunately the developers of the diff and patch programs took this into consideration and so these tools will not allow such changes to be applied without manual intervention. +When this state is reached, it is known as a "conflict". &kompare; will display conflicts so that you can manually resolve them, deciding +which changes should be applied to which file.</para> + +<para>&kompare; is also a great program for comparison of file changes on a folder level. When used to compare folders &kompare; recursively examines subfolders +and their file contents for differences. In this use case, each file where differences are found are automatically opened and +listed by &kompare; where easy navigation between the various files is possible.</para> + +</chapter> + +<chapter id="using"> +<title>Using &kompare;</title> + +<sect1 id="getting-started"> +<title>Getting Started</title> + +<para>This section provides instructions for starting &kompare; and provides a quick tour to the &kompare; main interface.</para> + +<sect2 id="starting-kompare"> +<title>Starting &kompare;</title> + +<para>A shortcut for starting &kompare; can be found in the K menu in the Development group +<menuchoice><guimenu>Development</guimenu><guimenuitem>Kompare</guimenuitem></menuchoice>.</para> + +<para>When &kompare; starts the first thing it does is display a dialog from +which to select the files you wish to compare. Special settings for the properties of the diff and the apprearance thereof can also be selected. +In the file form select a source and destination source to compare. This can be any two files, folders or a &URL; and a file. +Once the source and destination are selected click the <guibutton>Compare</guibutton> button.</para> + +<para>Once &kompare; has discovered the differences it will display the main interface. +When comparing two files or a url and a file the process takes just a few seconds. However, when comparing folders +with many subfolders and files, this process can take awhile.</para> + +<para>For explanation of the options available from diff and appearance forms see <xref linkend="configure-preferences"/>.</para> +</sect2> + +<sect2 id="main-interface"> +<title>The Main Interface</title> + +<para>This section provides a quick tour of the main interface which is comprised of the following areas:</para> +<itemizedlist> +<listitem><para>Menus</para></listitem> +<listitem><para>Toolbar</para></listitem> +<listitem><para>Source and Destination Folders</para></listitem> +<listitem><para>Source and Destination Files</para></listitem> +<listitem><para>Source and Destination Line Changes</para></listitem> +<listitem><para>Source and Destination Text View</para></listitem> +<listitem><para>Statusbar</para></listitem> +</itemizedlist> + +<sect3 id="menus"> +<title>Menus</title> +<para>&kompare; provides a menu driven interface. Explanation to the menu items and their options is provided in <xref linkend="command-reference"/>.</para> +</sect3> + +<sect3 id="toolbar"> +<title>Toolbar</title> +<para>The &kompare; toolbar provides shortcuts to the most frequently used diff and merge operations. +The toolbar orientation, text postioning, icon size properties and which shortcut icons are displayed can be customized from the +toobar context menu accessed when right-clicking the toolbar with the mouse. The toobar content menu also enables the toobar to be hidden. +If the toolbar is hidden and you wish to unhide it, select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Toolbar</guimenuitem></menuchoice>.</para> +</sect3> + +<sect3 id="source-destination-folders"> +<title>Source and Destination Folders</title> +<para>The source folder and destination folder panes display the folders in which compared files reside. +When many subfolders are included in the comparison, then selecting a folder will display the first document in +that folder where a difference was found between the source and destination.</para> +</sect3> + +<sect3 id="source-destination-files"> +<title>Source and Destination Files</title> +<para>The source and destination file pane displays files where a difference was found for the currently selected source or destination folder. +When a folder has multiple documents containing differences, all documents with a difference are listed. The selected document is displayed.</para> +</sect3> + +<sect3 id="source-destination-lines"> +<title>Source and Destination Line Changes</title> +<para>The source and destination line changes pane summarizes the differences found between the current source and destination documents. +Selecting a record within the pane highlights and selects the difference. This is a useful way to navigate and inspect long documents with many differences.</para> +</sect3> + +<sect3 id="source-destination-view"> +<title>Source and Destination View</title> +<para>The source and destination view is the main workspace of &kompare;. +The contents and highlighted differences of the currently selected source and destination file are displayed here with line numbers..</para> +</sect3> + +<sect3 id="text-view"> +<title>Text View</title> +<para>The <guilabel>Text View</guilabel> is not displayed by default. It can be opened by selecting +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Text View</guimenuitem></menuchoice>.</para> +<!-- Other than a notepad, what is this text view good for? --> +</sect3> + +<sect3 id="statusbar"> +<title>Statusbar</title> +<para>The status bar provides a summary of the current source and destination file or folder under comparison. +The status bar also reports the number of changes found in the current document and counts the differences that have been applied. +Furthermore, the status bar shows the overall number of documents containing differences and the current document number selected from this set. +For example, a comparison run over two folders may return 1890 files with differences. The currently selected document is number 18 of 1890.</para> +</sect3> +</sect2> +</sect1> + +<sect1 id="viewing-differences"> +<title>Viewing Differences</title> + +<sect2 id="managing-screen-real-estate"> +<title>Managing Screen Real-Estate</title> +<para>&kompare; displays the source and destination file under using equal percentage of the main interface view work area. +This view area provides some features that help optimize use of screen real-estate while viewing differences, including:</para> +<variablelist> +<varlistentry> +<term>Dual Scrollbars</term> +<listitem><para>The most obvious feature is that scrollbars are provided both on the right and bottom edges of the view area. +Using the scrollbars it is possible to move rapidly through the comparison.</para></listitem> +</varlistentry> +<varlistentry> +<term>Share Grip Handle</term> +<listitem><para>The vertical space between the source and destination view not only makes it possible to clearly see the start and end of lines in each of the panes, +but is also a grip handle that allows adjustment of percentage occupied between the source and destinate views that comprise the view pane. +To change pane size for one of the views, hover the mouse pointer over the grip handle then hold down the mouse button and drag left or right. +Naturally, increasing the area of one pane will decrease the area available to the opposite pane within the view panel area.</para></listitem> +</varlistentry> +<varlistentry> +<term>Docking</term> +<listitem><para>The main workspace can be undocked from the main interface by clicking the <guibutton>undock</guibutton> button located top right of the main workspace panel. +This opens the main workspace in a window of its own, allowing it to be maximized and resized across the screen.</para></listitem> +</varlistentry> +<varlistentry> +<term>Statusbar Toggle</term> +<listitem> +<para>The status bar of the view panel can be toggled ON/OFF by selecting <menuchoice><guimenu>Settings</guimenu><guimenuitem>Hide/Show Statusbar</guimenuitem></menuchoice>.</para> +</listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="switching-source-and-destination-view"> +<title>Switching Source and Destination Views</title> + +<para>Sometimes it can be useful to consider what the file to which differences where to be applied as the source. +For example, when comparing two modified versions of a file and discovering that the one file has many more modifications that the other. +The file with more changed would be better as the source, since then fewer differences would need to be applied.</para> +<para>In this case select <menuchoice><guimenu>File</guimenu><guimenuitem>Swap Source with Destination</guimenuitem></menuchoice>. +This will switch the files displayed in all &kompare; panels.</para> +</sect2> + +<sect2 id="display-difference-statistics"> +<title>Displaying Difference Statistics</title> +<para>For a quick overview of the differences, select <menuchoice><guimenu>File</guimenu><guimenuitem>Show Statistics</guimenuitem></menuchoice>. +This will display the <guilabel>Diff Statistics</guilabel> dialog. The following information is provided:</para> +<variablelist> +<varlistentry> +<term><guilabel>Old file:</guilabel></term> +<listitem><para>The file name of what is usually the destination file or file that is unmodified and to which differences will be applied.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>New file:</guilabel></term> +<listitem><para>The file name of what is usually the source file or file that is modified.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Format:</guilabel></term> +<listitem><para>The diff format used to display the difference (see <xref linkend="diff-format"/>).</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Number of hunks:</guilabel></term> +<listitem> +<para>The number of hunks found in the difference.</para> +<para>A hunk is a <quote>c<emphasis>hunk</emphasis></quote> of lines that have been marked as different between +source and destination and may include context lines depending on the diff format <guilabel>Lines of Context</guilabel> value (see <xref linkend="diff-format"/>).</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Number of differences</guilabel></term> +<listitem><para>The actual number of differences found, not hunks. A hunk can contain one or more differences +when the line change range and the context lines of any two or more changes overlap.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="navigating-the-difference-view"> +<title>Navigating the Difference View</title> +<para>&kompare; enables rapid navigation of differences on a file level and of multiple difference files when comparing folder trees.</para> + +<sect3 id="selecting-a-difference"> +<title>Selecting a Difference</title> +<para>A difference can be selected using by:</para> +<itemizedlist> +<listitem><para>clicking a line in the Source and Destination Line Changes pane (top right of the main window).</para></listitem> +<listitem><para>clicking the highlighted difference in the View pane.</para></listitem> +<listitem><para>traversing the listed differences in a comparison (see <xref linkend="traversing-differences"/>).</para></listitem> +</itemizedlist> +<para>When a difference is selected it is considered to be <quote>in focus</quote> and is displayed in a brighter color that non-selected differences.</para> +</sect3> + +<sect3 id="traversing-differences"> +<title>Traversing Differences</title> +<para>When a comparison finds many differences one of the best ways to approach reviewing them is to traverse the differences in a logical order, usually from top to bottom.</para> +<para>By default &kompare; selects the first difference found in a comparison. By selecting +<menuchoice><guimenu>Difference</guimenu><guimenuitem>Next Difference</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;<keycap>Down</keycap></keycombo>) the difference following the current selection is brought into focus. +To select the difference before the current difference +select <menuchoice><guimenu>Difference</guimenu><guimenuitem>Previous Difference</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;<keycap>Up</keycap></keycombo>).</para> +<para>In this way it is possible to traverse differences in an orderly manner, applying and unapply differences upon review.</para> +</sect3> + +<sect3 id="switching-between-files"> +<title>Switching Between Files</title> +<para>When a comparison is performed on folder level, many files may be found with differences. +A complete list of the files compared with difference found is provided in the <quote>Source and Destination Folders</quote>, +and <quote>Source and Destination Files</quote> panes. However, &kompare; displays differences between source and destination one comparison at time.</para> +<para>To switch between documents in this scenario the following options are available:</para> +<itemizedlist> +<listitem><para>Select the <quote>Source and Destination Folders</quote> pane to display file differences found in the +<quote>Source and Destination Files</quote> pane, then select a file.</para></listitem> +<listitem><para>Select <menuchoice><guimenu>Difference</guimenu><guimenuitem>Previous File</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;<keycap>PageUp</keycap></keycombo>) or +<menuchoice><guimenu>Difference</guimenu><guimenuitem>Next File</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;<keycap>PageDown</keycap></keycombo>) to +display the previous or next difference file found in the <quote>Source and Destination Files</quote> pane.</para> +</listitem> +</itemizedlist> +</sect3> +</sect2> +</sect1> + +<sect1 id="merging-differences"> +<title>Merging Differences</title> + +<para>&kompare; makes the task of applying and unapplying differences as simple as point and click. +Multiple apply and unapply operations can be performed on a difference as all operations are performed in memory and not written to the files on disk until the save operation is performed.</para> + +<sect2 id="applying-a-difference"> +<title>Applying a Difference</title> +<para>To apply a difference, click the highlighted difference region, then select +<menuchoice><guimenu>Difference</guimenu><guimenuitem>Apply Difference</guimenuitem></menuchoice> (<keycombo><keycap>Space</keycap></keycombo>).</para> +</sect2> + +<sect2 id="unapplying-a-difference"> +<title>Unapplying a Difference</title> +<para>To unapply a difference, click the highlighted difference region previously applied, then select +<menuchoice><guimenu>Difference</guimenu><guimenuitem>Unapply Difference</guimenuitem></menuchoice> (<keycombo><keycap>Backspace</keycap></keycombo>).</para> +</sect2> + +<sect2 id="applying-all-differences"> +<title>Applying All Differences</title> +<para>After reviewing differences between files and finding all acceptable it is possible apply them all with a single operation by selecting +<menuchoice><guimenu>Difference</guimenu><guimenuitem>Apply All</guimenuitem></menuchoice> (<keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo>).</para> +</sect2> + +<sect2 id="unapplying-all-differences"> +<title>Unapplying All Differences</title> +<para>To differences that have been applied select +<menuchoice><guimenu>Difference</guimenu><guimenuitem>Unapply All</guimenuitem></menuchoice> (<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo>).</para> +</sect2> + +<sect2 id="saving-changes"> +<title>Saving Changes</title> +<para>Once differences have been applied they can be saved by selecting +<menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> or +<menuchoice><guimenu>File</guimenu><guimenuitem>Save All...</guimenuitem></menuchoice>.</para> +<para>Applied differences are saved to both the source and destination file.</para> +</sect2> +</sect1> + +<sect1 id="working-with-diff-files"> +<title>Working with Diff Files</title> +<para>Diff files contain only the changes made between files, or a set of files within a folder system, and may or may not contain a number of context lines before and after line changes. +The sum of a line change and its context lines is known a hunk. A diff file therefore may contain multiple hunks from one or more files. +When the context lines of two or more hunks overlap, they are considered a single hunk. Diff files can be used to:</para> +<itemizedlist> +<listitem><para>Apply the changes contained in the hunks to an original file.</para></listitem> +<listitem><para>Apply the changes contained in the hunks to a file or set of original files within a folder system.</para></listitem> +<listitem><para>Modified before being applied to an original file or set of original files within a folder system.</para></listitem> +</itemizedlist> + +<sect2 id="creating-a-diff"> +<title>Creating a Diff</title> +<para>To create a diff file a comparison must be displayed in &kompare;. Assuming this is the case, then select <menuchoice><guimenu>File</guimenu><guimenuitem>Save .diff</guimenuitem></menuchoice>. +This will display the <guilabel>Diff Options</guilabel> dialog (see <xref linkend="diff-settings"/> for more information on diff formats and options). +After configuring these options, click the <guibutton>Save</guibutton> button and save the diff to a file with the extension <filename class="extension">.diff</filename>.</para> +</sect2> + +<sect2 id="displaying-a-diff"> +<title>Displaying a Diff</title> +<para>It is possible to display the contents of a diff file within &kompare; by opening the diff file from <menuchoice><guimenu>File</guimenu><guimenuitem>Open Diff...</guimenuitem></menuchoice>.</para> +<para>When viewing a diff file the hunks between the source and destination file are shown, remember that only the hunks are shown, no unmodified lines will be shown. +In some cases a diff file is created with 0 lines of context. In this case only the changed lines will be displayed.</para> +<para>When a diff file contains hunks from multiple files &kompare; displays the hunks from each file one at a time and you can +switch between files as though they were real files even though this information is only provided by the diff file contents.</para> +</sect2> + +<sect2 id="applying-a-diff"> +<title>Applying Differences in a Diff File</title> +<para>When viewing differences in a diff file it is possible to apply difference as you would when comparing source and destination files (see <xref linkend="merging-differences"/>).</para> +</sect2> + +<sect2 id="blending-a-diff"> +<title>Blending a &URL; with a Diff</title> +<para>In cases where a diff file is provided it is possible to compare the hunks in the diff against a file or folder. +To do this select <menuchoice><guimenu>File</guimenu><guimenuitem>Blend URL with Diff...</guimenuitem></menuchoice>. +Then input the <guilabel>File/Folder</guilabel> and <guilabel>Diff Output</guilabel> paths.</para> +<para>When viewing differences between a source file and a diff file it is possible to apply difference as you would when comparing source and destination files (see <xref linkend="merging-differences"/>).</para> +</sect2> + +</sect1> +</chapter> + +<chapter id="configure-preferences"> +<title>Configuring Preferences</title> + +<para>&kompare; enables users to set appearance preferences for difference formatting in the main interface and set behavioural properties of the diff program. +The <guilabel>Preferences</guilabel> dialog can be accessed by selecting +<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure &kompare;...</guisubmenu></menuchoice>.</para> + +<para>To configure preferences for appearance select the <guilabel>View</guilabel> menu item (see <xref linkend="view-settings"/>).</para> + +<para>To configure preferences for diff program properties select the <guilabel>Diff</guilabel> menu item (see <xref linkend="diff-settings"/>).</para> + +<sect1 id="view-settings"> +<title>View Settings</title> +<para>The <guimenu>View</guimenu> menu found on the <guilabel>Preferences</guilabel> dialog displays the <guilabel>Appearance</guilabel> +and <guilabel>Fonts</guilabel> tabbed forms.</para> + +<sect2 id="appearance"> +<title>Appearance</title> +<para>The <guilabel>Appearance</guilabel> form provides controls to manage the <guilabel>Colors</guilabel> used +to denote difference in the main interface, behaviour of the <guilabel>Mouse Wheel</guilabel> when jogging up and down +and how <guilabel>Tabs to Spaces</guilabel> conversion is managed.</para> +<screenshot> +<screeninfo>&kompare; Appearance Settings</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="settings-view1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&kompare; Appearance Settings</phrase> + </textobject> + </mediaobject> +</screenshot> +<variablelist> +<title>Color Group</title> +<para>To adjust color preferences used when displaying differences, click the color button to display the <guilabel>Select Color</guilabel> dialog for the following states:</para> +<varlistentry> +<term><guilabel>Removed color</guilabel></term> +<listitem><para>Lines that have been removed, do not exist, between source and destination.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Changed color</guilabel></term> +<listitem><para>Lines that have been changed, modified, between source and destination. </para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Added color</guilabel></term> +<listitem><para>Lines that have been added between source and destination.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Applied color</guilabel></term> +<listitem><para>Any of the above states where the difference has been applied between source and destination.</para></listitem> +</varlistentry> +</variablelist> +<variablelist> +<title>Mouse Wheel</title> +<varlistentry> +<term><guilabel>Number of lines</guilabel></term> +<listitem><para>The number of lines to jog the differences when turning the mouse wheel forward or backward.</para></listitem> +</varlistentry> +</variablelist> +<variablelist> +<title>Tabs to Spaces</title> +<varlistentry> +<term><guilabel>Number of spaces to convert a tab character to</guilabel></term> +<listitem><para>Convert each tab character to n space characters.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="fonts"> +<title>Fonts</title> +<screenshot> +<screeninfo>&kompare; Fonts Settings</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="settings-view2.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&kompare; Fonts Settings</phrase> + </textobject> + </mediaobject> +</screenshot> +<para>Select the font family and size to display when displaying differences.</para> +</sect2> +</sect1> + +<sect1 id="diff-settings"> +<title>Diff Settings</title> +<para>The <guimenu>Diff</guimenu> menu found on the <guilabel>Preferences</guilabel> dialog displays the <guilabel>Diff</guilabel>, +<guilabel>Format</guilabel>, <guilabel>Options</guilabel> and <guilabel>Exclude</guilabel> tabbed forms. These forms can be used to configure the +behavioural properties of the Diff program.</para> + +<sect2 id="diff"> +<title>Diff</title> +<screenshot> +<screeninfo>&kompare; Diff Settings</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="settings-diff1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&kompare; Diff Settings</phrase> + </textobject> + </mediaobject> +</screenshot> +<para>The command used to run the diff program (default <application>diff</application>).</para> +</sect2> + +<sect2 id="diff-format"> +<title>Format</title> +<screenshot> +<screeninfo>&kompare; Format Settings</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="settings-diff2.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&kompare; Format Settings</phrase> + </textobject> + </mediaobject> +</screenshot> +<para>Adjust options for the <guilabel>Output Format</guilabel> and number of <guilabel>Lines of Context</guilabel>.</para> +<variablelist> +<title>Output Format</title> +<varlistentry> +<term><guilabel>Context</guilabel></term> +<listitem> +<para>The context output format adds several lines of context around the lines that differ.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Ed</guilabel></term> +<listitem> +<para>diff can produce commands that direct the ed text editor to change the first file into the second file. +Historically, this was the only output mode suitable for automatically editing one file into another. +With the advent of <application>patch</application> this option is hardly ever used.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Normal</guilabel></term> +<listitem> +<para>The normal output format displays differing lines without any surrounding lines of context. </para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>RCS</guilabel></term> +<listitem> +<para>The RCS output format is designed specifically for use by the Revision Control System (<acronym>RCS</acronym>). +Like Ed format, this format is rarely used since the <application>patch</application> program was introduced.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Unified</guilabel></term> +<listitem> +<para>The unified output format is a variation on the context format. It is considered better than context because the +output is more compact than that of context as it omits redundant context lines.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Side-by-side</guilabel></term> +<listitem> +<para>Use the side by side output format which displays files listed in two columns with a gutter between them. This option is only available from the <guilabel>Diff Options</guilabel> dialog (see <xref linkend="creating-a-diff"/>).</para> +</listitem> +</varlistentry> +</variablelist> +<variablelist> +<title>Lines of Context</title> +<varlistentry> +<term><guilabel>Number of context lines</guilabel></term> +<listitem> +<para>When performing a diff with context or unified output format use this parameter to control the number of context lines included.</para> +</listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="options"> +<title>Options</title> +<screenshot> +<screeninfo>&kompare; OptionsSettings</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="settings-diff3.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&kompare; Options Settings</phrase> + </textobject> + </mediaobject> +</screenshot> +<para>The <guilabel>Options</guilabel> tab form allows configuration of the options supported by the diff program.</para> +<variablelist> +<title>General</title> +<varlistentry> +<term><guilabel>Look for smaller changes</guilabel></term> +<listitem><para>Forces diff to display changes in case, punctuation, space, &etc; when checked.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Optimise for large files</guilabel></term> +<listitem><para>Switches diff to process files with high-speed when checked.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Ignore changes in case</guilabel></term> +<listitem><para>Lower and Uppercase character changes are omitted when this option is checked.</para></listitem> +</varlistentry> +</variablelist> +<variablelist> +<title>Ignore regexp</title> +<varlistentry> +<term><guilabel>Ignore regexp</guilabel></term> +<listitem><para>Ignore lines matching a regular expression.</para></listitem> +</varlistentry> +</variablelist> +<variablelist> +<title>Whitespace</title> +<varlistentry> +<term><guilabel>Expand tabs to spaces in output</guilabel></term> +<listitem><para>When checked diff outputs will converts tab characters to the number of spaces defined in the +<guilabel>Preferences</guilabel> dialog <guimenu>View</guimenu> menu <guilabel>Tabs to Spaces</guilabel> option.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Ignore added or removed empty lines</guilabel></term> +<listitem><para>lines of zero length that differ between source and destination are ignored when this option is checked.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Ignore changes in the amount of whitespace</guilabel></term> +<listitem><para>White space before, after and between lines may change depending on different editors. +When this option is checked such changes are ignored.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Ignore all whitespace</guilabel></term> +<listitem><para>when checked white space differences are completely ignored.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Ignore changes due to tab expansion</guilabel></term> +<listitem><para>when checked white space resulting from tab characters is ignored.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="exclude"> +<title>Exclude</title> +<para>The <guilabel>Exclude</guilabel> form enables use of the filter options provided by the diff program.</para> +<screenshot> +<screeninfo>&kompare; Exclude Settings</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="settings-diff4.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&kompare; Exclude Settings</phrase> + </textobject> + </mediaobject> +</screenshot> +<variablelist> +<title>File Pattern to Exclude</title> +<varlistentry> +<term><guilabel>File Pattern to Exclude</guilabel></term> +<listitem><para>Exclude files based on wild card filtering</para></listitem> +</varlistentry> +</variablelist> +<variablelist> +<title>File with Filenames to Exclude</title> +<varlistentry> +<term><guilabel>File with Filenames to Exclude</guilabel></term> +<listitem><para>Define the filter based on the content of an externally managed file.</para></listitem> +</varlistentry> +</variablelist> +</sect2> +</sect1> + +</chapter> + +<chapter id="command-reference"> +<title>Command Reference</title> + +<sect1 id="file-menu"> +<title>The <guimenu>File</guimenu> Menu</title> +<variablelist> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guimenuitem>Open Diff...</guimenuitem></menuchoice></term> +<listitem><para>Displays the <guilabel>Open</guilabel> dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guimenuitem>Compare Files...</guimenuitem></menuchoice></term> +<listitem><para>Displays the <guilabel>Compare Files or Folders</guilabel> dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guimenuitem>Blend URL with Diff...</guimenuitem></menuchoice></term> +<listitem><para>Displays the <guilabel>Blend File/Folder with diff Output</guilabel> dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice></term> +<listitem><para>Writes applied differences to current source and or destination file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>File</guimenu><guimenuitem>Save All</guimenuitem></menuchoice></term> +<listitem><para>Writes applied differences to all source and or destination files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>File</guimenu><guimenuitem>Save .diff</guimenuitem></menuchoice></term> +<listitem><para>Displays the <guilabel>Diff Options</guilabel> dialog to define diff format and options.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>File</guimenu><guimenuitem>Swap Source with Destination</guimenuitem></menuchoice></term> +<listitem><para>Changes source and destination.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Show Statistics</guimenuitem></menuchoice></term> +<listitem><para>Displays the <guilabel>Display Statistics</guilabel> dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice></term> +<listitem><para>Exits &kompare;.</para></listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="difference-menu"> +<title>The <guimenu>Difference</guimenu> Menu</title> +<variablelist> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Difference</guimenu><guimenuitem>Unapply All</guimenuitem></menuchoice></term> +<listitem><para>Unapply all differences previously applied between source and destination.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>Backspace</keycap></shortcut> +<guimenu>Difference</guimenu><guimenuitem>Unapply Difference</guimenuitem></menuchoice></term> +<listitem><para>Revert a selected difference previously applied.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>Space</keycap></shortcut> +<guimenu>Difference</guimenu><guimenuitem>Apply Difference</guimenuitem></menuchoice></term> +<listitem><para>Apply a selected difference.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo> +</shortcut> +<guimenu>Difference</guimenu><guimenuitem>Apply All</guimenuitem></menuchoice></term> +<listitem><para>Apply all differences between source and destination.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>PageUp</keycap></keycombo> +</shortcut> +<guimenu>Difference</guimenu><guimenuitem>Previous File</guimenuitem></menuchoice></term> +<listitem><para>Make the previous difference, in the list of differences, the current file in the view pane.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>PageDown</keycap></keycombo> +</shortcut> +<guimenu>Difference</guimenu><guimenuitem>Next File</guimenuitem></menuchoice></term> +<listitem><para>Make the next difference, in the list of differences, the current file in the view pane.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Up</keycap></keycombo> +</shortcut> +<guimenu>Difference</guimenu><guimenuitem>Previous Difference</guimenuitem></menuchoice></term> +<listitem><para>Select the difference above the currently selected difference.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Down</keycap></keycombo> +</shortcut> +<guimenu>Difference</guimenu><guimenuitem>Next Difference</guimenuitem></menuchoice></term> +<listitem><para>Select the difference below the currently selected difference.</para></listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="settingsmenu"> +<title>The <guimenu>Settings</guimenu> Menu</title> +<variablelist> +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Hide/Show Toolbar</guimenuitem></menuchoice></term> +<listitem><para>Toggle the toolbar display ON/OFF.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show/Hide Statusbar</guimenuitem></menuchoice></term> +<listitem><para>Toggle the status bar display ON/OFF.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Text View</guimenuitem></menuchoice></term> +<listitem><para>Display the <guilabel>Text View</guilabel> pane.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term> +<listitem><para>Display the <guilabel>Configure Shortcuts</guilabel> dialog.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem></menuchoice></term> +<listitem><para>Display the <guilabel>Configure Toolbar</guilabel>.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kompare;...</guimenuitem></menuchoice></term> +<listitem><para>Display the &kompare; <guilabel>Preference</guilabel> dialog.</para></listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="help-menu"> +<title>The <guimenu>Help</guimenu> Menu</title> + +&help.menu.documentation; +</sect1> +</chapter> + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kompare; +</para> +<para> +Program copyright 2001-2004, &John.Firebaugh; &John.Firebaugh.mail; +and Otto Bruggeman<email>otto.bruggeman@home.nl</email> +</para> + +<para> +Documentation Copyright © 2007 Sean Wheller <email>sean@inwords.co.za</email> +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> +&underGPL; <!-- GPL License --> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kapp"> +<title>How to obtain &kompare;</title> + +&install.intro.documentation; + +</sect1> + + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +</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:ts=2:sw=2:tw=78:noet +--> diff --git a/doc/kompare/settings-diff1.png b/doc/kompare/settings-diff1.png Binary files differnew file mode 100644 index 00000000..58059c94 --- /dev/null +++ b/doc/kompare/settings-diff1.png diff --git a/doc/kompare/settings-diff2.png b/doc/kompare/settings-diff2.png Binary files differnew file mode 100644 index 00000000..f442aa94 --- /dev/null +++ b/doc/kompare/settings-diff2.png diff --git a/doc/kompare/settings-diff3.png b/doc/kompare/settings-diff3.png Binary files differnew file mode 100644 index 00000000..3b1612ce --- /dev/null +++ b/doc/kompare/settings-diff3.png diff --git a/doc/kompare/settings-diff4.png b/doc/kompare/settings-diff4.png Binary files differnew file mode 100644 index 00000000..b157afd3 --- /dev/null +++ b/doc/kompare/settings-diff4.png diff --git a/doc/kompare/settings-view1.png b/doc/kompare/settings-view1.png Binary files differnew file mode 100644 index 00000000..b07baa5b --- /dev/null +++ b/doc/kompare/settings-view1.png diff --git a/doc/kompare/settings-view2.png b/doc/kompare/settings-view2.png Binary files differnew file mode 100644 index 00000000..3fdbdf6e --- /dev/null +++ b/doc/kompare/settings-view2.png diff --git a/doc/scripts/Makefile.am b/doc/scripts/Makefile.am new file mode 100644 index 00000000..a695f510 --- /dev/null +++ b/doc/scripts/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG=en +KDE_MANS=AUTO +SUBDIRS = $(AUTODIRS) diff --git a/doc/scripts/kdesvn-build/Makefile.am b/doc/scripts/kdesvn-build/Makefile.am new file mode 100644 index 00000000..171f575c --- /dev/null +++ b/doc/scripts/kdesvn-build/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/scripts/kdesvn-build/index.docbook b/doc/scripts/kdesvn-build/index.docbook new file mode 100644 index 00000000..8dcadc9b --- /dev/null +++ b/doc/scripts/kdesvn-build/index.docbook @@ -0,0 +1,1324 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "kdesvn-build"> + <!ENTITY package "kdesdk"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> <!-- Change language only here --> + <!ENTITY svn "<application>Subversion</application>"> + <!ENTITY kdesvn-build "<application>kdesvn-build</application>"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>&kdesvn-build; Script Manual</title> + +<authorgroup id="authors"> +<author> +<firstname>Michael</firstname><surname>Pyne</surname> +<affiliation><address><email>michael.pyne@kdemail.net</email></address></affiliation> +</author> +<author> +<firstname>Carlos</firstname><surname>Woelz</surname> +<affiliation><address><email>carloswoelz@imap-mail.com</email></address></affiliation> +</author> + + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2005</year> +<holder>Michael Pyne</holder> +</copyright> + +<copyright> +<year>2005</year> +<holder>Carlos Woelz</holder> +</copyright> + + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-06-18</date> +<releaseinfo>0.98</releaseinfo> + +<abstract> +<para>The &kdesvn-build; is a Perl script which builds and installs &kde; directly from the sources found in the &kde; &svn; repository.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdesdk</keyword> +<keyword>SVN</keyword> +<keyword>Subversion</keyword> +<keyword>KDE development</keyword> +</keywordset> + +</bookinfo> + + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&kdesvn-build; is a Perl script to help users install <ulink +url="http://www.kde.org/">&kde;</ulink> from <ulink +url="http://subversion.tigris.org/">&svn;</ulink>. You may also want to +consider the kde-build script include with &kde;'s kdesdk module. +</para> + +<para> +Here we document the &kdesvn-build; configuration file syntax and options, its +command line options, features, and an overview of all necessary steps required +to build &kde; from source, including the steps which you should perform using +other tools, or in other words, steps that are not automatically performed +by the &kdesvn-build; script. +</para> + +</chapter> + +<chapter id="getting-started"> +<title>Getting Started</title> + +<para> +In this chapter, we show how to use the &kdesvn-build; to checkout modules from the +&kde; repository and build them. We also provide a basic explanation of the &kde; +&svn; structure and the steps you have to perform before running the script. +</para> + +<para> +All topics present in this chapter are covered with even more detail in the +<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php"> +Building &kde; from Source Step by Step Guide</ulink>, at the +<ulink url="http://quality.kde.org">&kde; Quality Team Website</ulink>. +If you are compiling KDE for the first time, it is a good idea to read +it, or consult it as a reference source. You will find detailed information +about packaging tools and requirements, common compilation pitfalls and +strategies and information about running your new &kde; installation. +</para> + +<sect1 id="before-building"> +<title>Preparing the System to Build &kde;</title> + +<para> +It is recommended that you download and build &kde; using a user +account. If you already have &kde; packages installed, the best choice +would be to create a different (dedicated) user to build and run the new &kde;. +The advantage of building &kde; with a dedicated user is you can not break +the base system, and you will always have a way to comfortably work when +things go wrong. +</para> + +<para> +Later, you can do a root installation if you wish. This document +does not cover a root installation. If you are performing a system +wide install, you probably already know what you are doing anyway. +</para> + +<para>Before using the &kdesvn-build; script (or any other building +strategy) you must install the development tools and libraries needed for &kde;. +You need the Qt library, version 3.3.0 or greater, Automake 1.8, +Autoconf 2.5X (better if >=2.57 as a bug was reported with lower versions), +the subversion (svn) client, the gcc compiler with C++ support, libxml2, +openssl, libbz2, and many more (for a complete list, visit the +<ulink url="http://www.kde.org/info/requirements/3.4.php">KDE Compilation +Requirements</ulink>). You can usually get those tools packaged for your system +from your distribution or vendor. +</para> + +<para> +Some of these packages are divided into libs, programs or utilities and +development packages. You will need at least the program or library and +its development package. If in doubt, install all. The libraries you need +will change depending on the modules you intend to build, as each module +has its own requirements. The +<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php#step1"> +Building &kde; from Source Step by Step Guide</ulink> has more details +about the specific tools and techniques used to install and find the +required software. +</para> + +<para> +You probably already have a version of the &kdesvn-build; script installed +in your system. &kdesvn-build;requires you to create a configuration file, named +<filename>.kdesvn-buildrc</filename>. This file should be installed on +the home folder (~/), and contain all configuration data +required for the script to run, like configuration options, +compiling options, location of the sources, the destination of the installation +(prefix), the modules that should be built, &etc;. The default configuration +data is provided by the <filename>kdesvn-buildrc-sample</filename> file. +You can find more information about the syntax of the configuration file +in <xref linkend="configure-data" /> and in <xref linkend="kdesvn-buildrc" />. +</para> + +<para> +A good way to get the latest version is to browse the kdesdk/scripts page +at the <ulink url="http://websvn.kde.org/trunk/KDE">websvn.kde.org</ulink> website. +You will see a list of the files available in the kdesdk/scripts directory in +the &kde; &svn; repository. Click the &kdesvn-build; link and download +the latest version of the script. Do the same for the +<filename>kdesvn-buildrc-sample</filename> file. +Make the script executable, and be sure it is in your path. +</para> + +</sect1> + +<sect1 id="configure-data"> +<title>Setting the Configuration Data</title> + +<para> +To use the script, you must have a file in your home directory called +<filename>.kdesvn-buildrc</filename>, which sets the general options and sets the modules +you would like to download and build. +</para> + +<para> +Use the <filename>kdesvn-buildrc-sample</filename> file as a +template, setting global options, and the modules you want to build. +</para> + +<para> +Select the server used to check out from &svn;, by setting the svn-server +global option. The default is the anonymous &svn; repository, +<emphasis>svn://anonsvn.kde.org/</emphasis>, but change it +if you have a <ulink url="http://developer.kde.org/documentation/misc/firststepsaccount">&kde; +&svn; account</ulink>, or if there is <ulink url="http://developer.kde.org/source/anonsvn.html"> +a mirror close to you</ulink>. +</para> + +<para> +Pay close attention to the kdedir and qtdir global variables, as the first sets +where your &kde; build is going to be installed, (by default to +<filename>~/kde</filename>), and the second where (and if) your qt library is +going to be built and installed, (by default to +<filename>~/kdesvn/build/qt-copy</filename>). You will need to know the +kdedir and qtdir location later, to set up the environment variables +that are necessary to run your new installation. +Check if the listed modules are in fact the modules you want to build. +The default options from the <filename>kdesvn-buildrc-sample</filename> file +should be enough to get a fairly complete &kde; installation. +Save the resulting as <filename>.kdesvn-buildrc</filename> in your home +folder. +</para> + +<para> +If you wish to fine tune your <filename>.kdesvn-buildrc</filename>, +consult <xref linkend="kdesvn-buildrc" /> for detailed information +about all configuration options. +</para> + +</sect1> + +<sect1 id="building-and-troubleshooting"> +<title>Using the &kdesvn-build; script</title> + +<para> +Now you are ready to run the script. From a terminal window, +log in to the user you are using to compile &kde; and execute +the script: +<screen> +<prompt>%</prompt><command>su</command> <option>-</option> <replaceable>devel-username</replaceable> +<prompt>%</prompt><command>kdesvn-build</command> +</screen> +</para> + +<para> +Now, the script should start downloading the sources and compiling them. It is +unlikely that you will succeed in the first time you compile &kde;. Do not despair! +Check the log files to see if you are missing some tools or development packages +(the location of the log files is set by the log-dir variable in the configuration +file). Sometimes, the main development branch get very unstable and hard to build, +especially when a development freeze is close. Be patient. You can find more common +examples of things that can go wrong and their solutions, as well as general tips and +strategies to build &kde; in the +<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php#step1"> +Building &kde; from Source Step by Step Guide</ulink>. +</para> + +</sect1> + +<sect1 id="environment"> +<title>Setting the Environment to Run Your Fresh &kde;</title> + +<para> +Assuming you are using a dedicated user to build &kde;, and you already have +an installed &kde; version, running your new &kde; may be a bit tricky, as the new &kde; +has to take precedence over the old. Change the environment variables to +make sure it does. +</para> + +<para> +Open or create the <filename>.bash_profile</filename> file in the home directory with your favorite editor, +and add to the end of the file: + +<programlisting> +KDEDIR=(path to kdedir) +KDEDIRS=$KDEDIR +PATH=$KDEDIR/bin:$QTDIR/bin:$PATH +LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH +export KDEDIRS PATH LD_LIBRARY_PATH +</programlisting> + +If you are building the qt-copy module, add instead: + +<programlisting> +QTDIR=(path to qtdir) +KDEDIR=(path to kdedir) +KDEDIRS=$KDEDIR +PATH=$KDEDIR/bin:$QTDIR/bin:$PATH +MANPATH=$QTDIR/doc/man:$MANPATH +LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH +export QTDIR KDEDIRS PATH MANPATH LD_LIBRARY_PATH +</programlisting> +</para> + +<para> +If you are not using a dedicated user, set a different <envar>$KDEHOME</envar> for your +new environment in your <filename>.bash_profile</filename>: + +<programlisting> +export KDEHOME="${HOME}/.kde-svn" + +# Create it if needed +[ ! -e ~/.kde-svn ] && mkdir ~/.kde-svn +</programlisting> +</para> + +<note> +<para> +If later your menu is empty or too crowded with applications from your distribution, +you may have to set the xdg environment variables in your <filename>.bash_profile</filename>: + +<programlisting> +XDG_CONFIG_DIRS="/etc/xdg" +XDG_DATA_DIRS="${KDEDIR}/share:/usr/share" +export XDG_CONFIG_DIRS XDG_DATA_DIRS +</programlisting> + +</para> +</note> + +<para> +Now that we are done with the you have to make sure that the right <application>startkde</application> +script is going to be used: +</para> + +<para> +Open the <filename>.xinitrc</filename> text file (or <filename>.xsession</filename>, +depending on the distribution) from the home directory, or create it if necessary. Add the +line: + +<programlisting> +exec ${KDEDIR}/bin/startkde +</programlisting> +</para> + +<para> +Now start your fresh &kde;: in BSD and Linux systems with virtual terminal support, +Ctrl+Alt+F1...F12 keystroke combinations are used to switch to Virtual Console 1 through 12. +This allows you to run more than one desktop environment at the same time. The fist six are +text terminals and the following six are graphical displays. +</para> + +<para> +If when you boot you are presented to the graphical display manager instead, you can +use the new KDE environment, even if it is not listed as an option. Press Crtl + Alt + F2, +and you will be presented to a text terminal. Log in using the dedicated user and type: +</para> + +<screen> +startx -- :1 +</screen> + +<tip> +<para> +You can run the KDE from sources and the old KDE at the same time! Log in using your regular user, +start the stable KDE desktop. Press Crtl + Alt + F2 (or F1, F3, etc..), and you will be presented +to a text terminal. Log in using the dedicated user and type "startx -- :1". You can go back to the +regular user by pressing Crtl + Alt + F6 (Or F7, F8, etc... Try them out! One of them is the right +one.) To return to KDE from sources, press Crtl + Alt + F7 (or F6, F8,etc..). Now you can switch +between your KDE versions, and test the new one knowing you can quickly return to the safety of +the stable KDE desktop. +</para> +</tip> + + +</sect1> + +</chapter> + +<chapter id="features"> +<title>Script Features</title> + +<para> +&kdesvn-build; features include: +</para> + + +<itemizedlist> + +<listitem><para> +Automatically checks out or updates modules from &svn;, as +appropriate. +</para></listitem> + +<listitem><para> +Times the build process for modules. +</para></listitem> + +<listitem><para> +Automatically tries to rebuild modules that were using incremental +make, which is prone to failure after certain kinds of commits. +</para></listitem> + +<listitem><para> +Can resume a previous script, or start the build process from a particular +module. +</para></listitem> + +<listitem><para> +Comes built-in with a sane set of default options appropriate for building +a base &kde; single-user installation from the anonymous &svn; repository. +</para></listitem> + +<listitem><para> +Comes with <ulink url="http://www.kde.me.uk/index.php?page=unsermake">Unsermake</ulink> +support. +</para></listitem> + +<listitem><para> +Tilde-expansion for your configuration options. For example, you can +specify: +<programlisting>qtdir ~/kdesvn/build/qt-copy</programlisting> +</para></listitem> + +<listitem><para> +Configurable build, source, and logging directories +</para></listitem> + +<listitem><para> +Automatically sets up a build system, with the source directory not the +same as the build directory, in order to keep the source directory +pristine. The exception is <application>qt-copy</application>, which is not designed to be built like +that (unless you would like to test the +<link linkend="conf-use-qt-builddir-hack"><quote>qt with a separate build directory hack</quote></link>). +</para></listitem> + +<listitem><para> +You can specify global options to apply to every module to check out, and +you can specify options to apply to individual modules as well. +</para></listitem> + +<listitem><para> +Since the autotools sometimes get out of sync with changes to the +source tree, you can force a rebuild of a module by creating a file called +.refresh-me in the build directory of the module in question, or by running +&kdesvn-build; with the <option>--refresh-build</option> option. +</para></listitem> + +<listitem><para> +You can specify various environment values to be used during the build, +including <envar>KDEDIR</envar>, <envar>QTDIR</envar>, <envar>DO_NOT_COMPILE</envar>, +and <envar>CXXFLAGS</envar>. +</para></listitem> + +<listitem><para> +Command logging. Logs are dated and numbered so that you always have a +log of a script run. Also, a special symlink called latest is created to +always point to the most recent log entry in the log directory. +</para></listitem> + +<listitem><para> +If you are using a user build of &kde; instead of a system build (for which +you must be root to install), you can use the script to install for you. I +haven not audited this code, and it makes ample use of the <function>system()</function> +call, so I would not recommend running it as root at this point. +</para></listitem> + +<listitem><para> +You can use <link linkend="conf-make-install-prefix">make-install-prefix</link> to +prefix the make install command line with a separate command, which is useful +for sudo. +</para></listitem> + +<listitem><para> +You can use the <link linkend="conf-apidox">apidox</link> option to automatically +build and install the API documentation for some modules. +</para></listitem> + +<listitem><para> +You can check out only a portion of a &kde; &svn; module. For example, +you could check out only the <application>taglib</application> from +<application>kdesupport</application>, or only <application>K3B</application> from +<application>extragear/multimedia</application>. The script will automatically pull in +<application>kde-common</application> if necessary to make the build work. +</para></listitem> + +<listitem><para> +You can <quote>pretend</quote> to do the operations. If you pass +<option>--pretend</option> or <option>-p</option> on the +command line, the script will give a very verbose description of the commands +it is about to execute, without actually executing it. +</para></listitem> + +<listitem><para> +Support for checking out specific branches of &svn; +modules. This work still needs to be completed, but you already select the branch you +want to build using the <link linkend="conf-module-base-path">module-base-path +configuration option</link>. +</para></listitem> + +</itemizedlist> + +<para> +Things that &kdesvn-build; does NOT do: +</para> + +<itemizedlist> + +<listitem><para> +Find the fastest &kde; &svn; mirror. There is not even a list shipped +with the script at this point, although the default server should work +fine. +</para></listitem> + +<listitem><para> +Brush your teeth. You should remember to do that yourself. +</para></listitem> + +<listitem><para> +The script probably is not bug-free. Sorry. +</para></listitem> + +</itemizedlist> + +</chapter> + +<chapter id="kdesvn-buildrc"> +<title>The Format of .kdesvn-buildrc</title> + +<para> +To use the script, you must have a file in your home directory called +<filename>.kdesvn-buildrc</filename>, which describes the modules you would +like to download and build. +</para> + + + +<para> +It starts with the global options, specified like the following: +</para> + +<programlisting> +global +<replaceable>option-name option-value</replaceable> +<replaceable>[...]</replaceable> +end global +</programlisting> + +<para> +It is then followed by one or more module sections, specified like the +following: +</para> + +<programlisting> +module <replaceable>module-name</replaceable> +<replaceable>option-name option-value</replaceable> +<replaceable>[...]</replaceable> +end module +</programlisting> + +<para> +<replaceable>module-name</replaceable> must be a module from the &kde; &svn; repository (for +example, kdelibs or kdebase). Some options override global options, some +add to global options, and some global options simply can't be overridden. +</para> + +<para> +The following is an alphabetized list of options you can use. Click on the +option to find out more about it. If one is not documented, please e-mail the +authors using the address you can find <link linkend="authors">above</link>. +</para> + +<itemizedlist> +<listitem><para><link linkend="conf-apidox">apidox</link>, to build API Documentation</para></listitem> +<listitem><para><link linkend="conf-apply-qt-patches">apply-qt-patches</link>, to enhance qt-copy</para></listitem> +<listitem><para><link linkend="conf-binpath">binpath</link>, to set the <envar>PATH</envar> variable.</para></listitem> +<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of /trunk.</para></listitem> +<listitem><para><link linkend="conf-build-dir">build-dir</link>, to set the directory to build in.</para></listitem> +<listitem><para><link linkend="conf-checkout-only">checkout-only</link>, to checkout only parts of a module.</para></listitem> +<listitem><para><link linkend="conf-colorful-output">colorful-output</link> to add color to the script output.</para></listitem> +<listitem><para><link linkend="conf-configure-flags">configure-flags</link> to define what flags to configure a module with.</para></listitem> +<listitem><para><link linkend="conf-cxxflags">cxxflags</link> to define the <envar>CXXFLAGS</envar> variable.</para></listitem> +<listitem><para><link linkend="conf-dest-dir">dest-dir</link> to change the directory name for a module.</para></listitem> +<listitem><para><link linkend="conf-disable-agent-check">disable-agent-check</link>, to keep kdesvn-build from checking on ssh-agent's status.</para></listitem> +<listitem><para><link linkend="conf-do-not-compile">do-not-compile</link>, to mark directories to skip building.</para></listitem> +<listitem><para><link linkend="conf-inst-apps">inst-apps</link>, to only build and install some directories.</para></listitem> +<listitem><para><link linkend="conf-install-after-build">install-after-build</link>, to avoid installing after the build process.</para></listitem> +<listitem><para><link linkend="conf-kdedir">kdedir</link>, to set the directory to install KDE to.</para></listitem> +<listitem><para><link linkend="conf-libpath">libpath</link>, to set the <envar>LD_LIBRARY_PATH</envar> variable.</para></listitem> +<listitem><para><link linkend="conf-make-install-prefix">make-install-prefix</link>, to run a helper program (like sudo) during make install.</para></listitem> +<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the make program.</para></listitem> +<listitem><para><link linkend="conf-manual-build">manual-build</link>, to avoid building the module automatically.</para></listitem> +<listitem><para><link linkend="conf-manual-update">manual-update</link>, to avoid doing anything to the module automatically.</para></listitem> +<listitem><para><link linkend="conf-module-base-path">module-base-path</link>, to change where to download the module from (useful for branches and tags).</para></listitem> +<listitem><para><link linkend="conf-niceness">niceness</link>, to change the CPU priority.</para></listitem> +<listitem><para><link linkend="conf-no-rebuild-on-fail">no-rebuild-on-fail</link>, to avoid running make again if it fails.</para></listitem> +<listitem><para><link linkend="conf-qtdir">qtdir</link>, to set the path to Qt.</para></listitem> +<listitem><para><link linkend="conf-set-env">set-env</link>, to set an environment variable.</para></listitem> +<listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem> +<listitem><para><link linkend="conf-stop-on-failure">stop-on-failure</link>, to make kdesvn-build stop as soon as a failure is encountered.</para></listitem> +<listitem><para><link linkend="conf-svn-server">svn-server</link>, to change the server the sources are downloaded from.</para></listitem> +<listitem><para><link linkend="conf-use-qt-builddir-hack">use-qt-builddir-hack</link>, to give Qt a separate build directory from its source like KDE.</para></listitem> +<listitem><para><link linkend="conf-use-unsermake">use-unsermake</link>, to use the advanced unsermake build system.</para></listitem> +</itemizedlist> + + +<para> +Here is a table of the various options, and some comments on them. Any +option which overrides the global option will override a command line setting +as well. +</para> + +<table id="option-table"> +<title>Table of Options</title> +<tgroup cols="3"> + +<thead> +<row> +<entry>Option-name</entry> +<entry>Module -> Global Behavior</entry> +<entry>Notes</entry> +</row> +</thead> + +<tbody> + +<row id="conf-apidox"> +<entry>apidox</entry> +<entry>Overrides global</entry> +<entry>Set this option to <quote>true</quote> in order to have &kdesvn-build; automatically +build and install the API documentation for the module after the normal build/install +process. This only works for modules where <command>make apidox</command> does something, +including kdelibs, kdebase, and koffice, among others. +</entry> +</row> + +<row id="conf-apply-qt-patches"> +<entry>apply-qt-patches</entry> +<entry>Overrides global</entry> +<entry>This option is only useful for qt-copy. If it is set to a non-zero value, +then the apply-patches script in qt-copy will be run prior to building, in +order to apply the non-official patches to the qt-copy. Since these patches +are normally the reason for using qt-copy instead of a stock Qt, it shouldn't +do any harm to enable it. The default is to enable the patches.</entry> +</row> + +<row id="conf-binpath"> +<entry>binpath</entry> +<entry>Can't be overridden</entry> +<entry><para>Set this option to set the environment variable PATH while building. +You can't override this setting in a module option. The default value is +<filename class="directory">/bin:/usr/bin:/usr/local/bin:/usr/X11R6/bin</filename>. This environment +variable should include the colon-separated paths of your development +toolchain. The paths <filename class="directory">$KDEDIR/bin</filename> and +<filename class="directory">$QTDIR/bin</filename> are automatically added. You +may use the tilde (~) for any paths you add using this option.</para> +</entry> +</row> + +<row id="conf-branch"> +<entry>branch</entry> +<entry>Overrides global</entry> +<entry><para>Set this option to checkout from a branch of KDE instead of the +default of "trunk", where KDE development occurs. For instance, to checkout +KDE 3.4 branch, you would set this option to "3.4".</para> +<para>Note that some modules use a different branch name. Notably, the +required arts module doesn't go by KDE version numbers. The arts that +accompanied KDE 3.4 was version 1.4.</para> +<para>If kdesvn-build fails to properly download a branch with this option, you +may have to manually specify the URL to download from using the <link +linkend="conf-override-url">override-url</link> option.</para> +</entry> +</row> + +<row id="conf-build-dir"> +<entry>build-dir</entry> +<entry>Overrides global</entry> +<entry>Use this option to change the directory to contain the built sources. There +are three different ways to use it: +<itemizedlist> + +<listitem><para>Relative to the &kde; &svn; source directory (see <link +linkend="conf-source-dir">the source-dir option</link>). This is the default, and +the way the script worked up to version v0.61. This mode is selected if you +type a directory name that doesn't start with a tilde (~) or a slash (/).</para> +<para>The default value is <filename class="directory">build</filename>.</para></listitem> + +<listitem><para>Absolute path. If you specify a path that begins with a /, then that path +is used directly. For example, <filename class="directory">/tmp/kde-obj-dir/</filename>.</para></listitem> + +<listitem><para>Relative to your home directory. If you specify a path that begins with a +~, then the path is used relative to your home directory, analogous to the +shell's tilde-expansion. For example, <filename class="directory">~/builddir</filename> would set the build +directory to <filename class="directory">/home/user-name/builddir</filename>.</para></listitem> + +</itemizedlist> + +Perhaps surprisingly, this option can be changed per module. + +</entry> +</row> + +<row id="conf-checkout-only"> +<entry>checkout-only</entry> +<entry>Overrides global</entry> +<entry>Set this option to checkout &svn; sources piece by piece. The value +for this option should be a space separated list of directories to checkout. +If you don't include the admin directory, it will automatically be included (if +necessary). When checking out piece by piece, the admin directory will be +pulled in from kde-common, which is where it exists on the &svn; server. +Although this option overrides the global option, be aware that setting this as +a global option makes no sense. +</entry> +</row> + +<row id="conf-configure-flags"> +<entry>configure-flags</entry> +<entry>Appends to global option(except for qt-copy)</entry> +<entry>Use this option to specify what flags to pass to ./configure when creating +the build system for the module. When this is used as a global-option, it is +applied to all modules that this script builds. qt-copy uses a much different +set of configure options than the rest of &kde;, so this option +<emphasis>overrides</emphasis> the global settings when applied to qt-copy.</entry> +</row> + +<row id="conf-colorful-output"> +<entry>colorful-output</entry> +<entry>Can't be overridden</entry> +<entry>Set this option to false to disable the colorful output of &kdesvn-build;. +This option defaults to <quote>true</quote>. Note that &kdesvn-build; won't output the +color codes to anything but a terminal (such as xterm, &konsole;, or the normal +Linux console). +</entry> +</row> + +<row id="conf-cxxflags"> +<entry>cxxflags</entry> +<entry>Appends to global option</entry> +<entry>Use this option to specify what flags to pass to <command>./configure</command> as the +<envar>CXXFLAGS</envar> when creating the build system for the module. This option is +specified here instead of with <link +linkend="conf-configure-flags">configure-flags</link> because this option will also +set the environment variable <envar>CXXFLAGS</envar> during the build process. +</entry> +</row> + +<row id="conf-dest-dir"> +<entry>dest-dir</entry> +<entry>Overrides global</entry> +<entry>Use this option to change the name a module is given on disk. For +example, if your module was extragear/network, you could rename it to +extragear-network using this option. +</entry> +</row> + +<row id="conf-disable-agent-check"> +<entry>disable-agent-check</entry> +<entry>Can't be overridden</entry> +<entry>Normally if you're using SSH to download the Subversion sources (such as +if you're using the svn+ssh protocol), kdesvn-build will try and make sure that +if you're using ssh-agent, it is actually managing some SSH identities. This is +to try and prevent SSH from asking for your passphrase for every module. You can +disable this check by setting disable-agent-check to true. +</entry> +</row> + +<row id="conf-do-not-compile"> +<entry>do-not-compile</entry> +<entry>Overrides global</entry> +<entry><para>Use this option to set the <envar>DO_NOT_COMPILE</envar> environment variable prior to +running the configure script. According to the <ulink +url="http://developer.kde.org/documentation/other/developer-faq.html">&kde; +Developer FAQ</ulink>, this should cause any toplevel directory you pass to not be +built. The directories should be space-separated.</para> + +<para>Note that the sources to the programs will still be downloaded. You can use +the <link linkend="conf-checkout-only">checkout-only</link> +directive to choose directories that you want to check out.</para> +</entry> +</row> + +<row id="conf-email-address"> +<entry>email-address</entry> +<entry>Can't be overridden</entry> +<entry> +<para>Set this option to the e-mail address kdesvn-build should send from should +it ever need to send e-mail. You do not need to worry about this if you don't +use any feature which send e-mail. (They are all disabled by default). +</para> + +<para>Currently only <link linkend="conf-email-on-compile-error">email-on-compile-error</link> +needs this option. +</para> +</entry> +</row> + +<row id="conf-email-on-compile-error"> +<entry>email-on-compile-error</entry> +<entry>Can't be overridden</entry> +<entry> +<para>You can set this option to the email address to send a report to when a +module fails to build. kdesvn-build will wait until all the modules are done +and collate all of the results in the report. The report is only sent if a +module fails to build. +</para> + +<para>Please see the <link linkend="conf-email-address">email-address</link> +option to set the address kdesvn-build should send from, since the default +is usually not what you want. +</para> +</entry> +</row> + +<row id="conf-inst-apps"> +<entry>inst-apps</entry> +<entry>Overrides global</entry> +<entry><para>This is the opposite of the <link +linkend="conf-do-not-compile">do-not-compile</link> option. This option makes it +so that only the given toplevel directories are built. The directories should +be space-separated.</para> + +<para>Any changes don't take effect until the next time +<command>make <option>-f</option> Makefile.cvs</command> is +run, either automatically by the script, or manually by the <link +linkend="cmdline-refresh-build"><option>--refresh-build</option></link> or <link +linkend="cmdline-recreate-configure"><option>--recreate-configure</option></link> options. +</para> + +<para>Note that the sources to the programs will still be downloaded. You can use +the <link linkend="conf-checkout-only">checkout-only</link> +directive to choose directories that you want to check out.</para> +</entry> +</row> + +<row id="conf-install-after-build"> +<entry>install-after-build</entry> +<entry>Overrides global</entry> +<entry>This option is used to install the package after it successfully builds. +This option is enabled by default. If you want to disable this, you need to +set this option to 0 in the configuration file. You can also use the +<link linkend="cmdline-no-install"><option>--no-install</option></link> command line flag. +</entry> +</row> + +<row id="conf-kdedir"> +<entry>kdedir</entry> +<entry>Can't be overridden</entry> +<entry>This option sets the directory that &kde; will be installed to after it is +built. It defaults to <filename class="directory">~/kde</filename>. If you change this to a directory +needing root access, you may want to read about the <link +linkend="conf-make-install-prefix">make-install-prefix</link> option as well.</entry> +</row> + +<row id="conf-libpath"> +<entry>libpath</entry> +<entry>Can't be overridden</entry> +<entry>Set this option to set the environment variable LD_LIBRARY_PATH while +building. You can't override this setting in a module option. The default +value is blank, but the paths <filename class="directory">$KDEDIR/lib</filename> and +<filename class="directory">$QTDIR/lib</filename> are automatically +added. You may use the tilde (~) for any paths you add using this option. +</entry> +</row> + +<row id="conf-log-dir"> +<entry>log-dir</entry> +<entry>Overrides global</entry> +<entry>Use this option to change the directory used to hold the log files +generated by the script. This setting can be set on a per-module basis as of +version 0.64 or later. +</entry> +</row> + +<row id="conf-make-install-prefix"> +<entry>make-install-prefix</entry> +<entry>Overrides global</entry> +<entry>Set this variable to a space-separated list, which is interpreted as a +command and its options to precede the make install command used to install +modules. This is useful for installing packages with sudo for example, but +please be careful while dealing with root privileges.</entry> +</row> + +<row id="conf-make-options"> +<entry>make-options</entry> +<entry>Overrides global</entry> +<entry>Set this variable in order to pass command line options to the make +command. This is useful for programs such as <ulink +url="http://distcc.samba.org/"><application>distcc</application></ulink>. +<application>distcc</application> allows you to share your +compilation work among more than one computer. To use it, you must use the +<option>-j</option> option to make. Now you can. According to the docs, 2 * +number_of_network_cpus is recommended. I have 1 CPU total, so it would be +<option>-j2</option> in my case.</entry> +</row> + +<row id="conf-manual-build"> +<entry>manual-build</entry> +<entry>Overrides global</entry> +<entry>Set the option value to <quote>true</quote> to keep the build process from attempting to +build this module. It will still be kept up-to-date when updating from &svn;. +This option is exactly equivalent to the <link +linkend="cmdline-no-build"><option>--no-build</option></link> command line option. +</entry> +</row> + +<row id="conf-manual-update"> +<entry>manual-update</entry> +<entry>Overrides global</entry> +<entry>Set the option value to <quote>true</quote> to keep the build process from attempting to +update (and by extension, build or install) this module. If you set this +option for a module, then you have pretty much commented it out. +</entry> +</row> + +<row id="conf-module-base-path"> +<entry>module-base-path</entry> +<entry>Overrides global</entry> +<entry><para>Set this option to override &kdesvn-build;'s default directory path to the +module in question. This can be used, for example, to pull specific branches +or tagged versions of libraries. <ulink url="http://websvn.kde.org/">The &kde; +Source Viewer</ulink> is invaluable in helping to pick the right path.</para> +<para>Note that &kdesvn-build; constructs the final path according to the +following template: +<varname>$svn-server</varname>/home/kde/<varname>$module-base-path</varname>/<varname>$module-name</varname>. +</para> +<para>The default value is either <quote>trunk</quote> or +<quote>trunk/KDE</quote>, depending on the modulename.</para> +</entry> +</row> + +<row id="conf-niceness"> +<entry>niceness</entry> +<entry>Can't be overridden</entry> +<entry>Set this option to a number between 20 and 0. The higher the number, the +lower a priority &kdesvn-build; will set for itself. The default is 10. +</entry> +</row> + +<row id="conf-no-rebuild-on-fail"> +<entry>no-rebuild-on-fail</entry> +<entry>Overrides global</entry> +<entry>Set this option value to <quote>true</quote> to always prevent &kdesvn-build; from trying +to rebuild this module if it should fail an incremental build. Normally +&kdesvn-build; will try to rebuild the module from scratch to counteract the +effect of a stray &svn; update messing up the build system.</entry> +</row> + +<row id="conf-override-url"> +<entry>override-url</entry> +<entry>Overrides global</entry> +<entry>If you set this option, kdesvn-build will use its value as the URL +to pass to Subversion <emphasis>completely unchanged</emphasis>. You should +generally use this if you want to download a specific release but kdesvn-build +can't figure out what you mean using <link linkend="conf-branch">branch</link>. +</entry> +</row> + +<row id="conf-qtdir"> +<entry>qtdir</entry> +<entry>Can't be overridden</entry> +<entry>Set this option to set the environment variable QTDIR while building. +You can't override this setting in a module option. If you don't specify +this option, it defaults to +<filename class="directory"><varname>$(source-dir)</varname>/build/qt-copy</filename>, +which uses the qt-copy module included in the &kde; source repository. +You may use a tilde (~) to represent your home directory. +</entry> +</row> + +<row id="conf-remove-after-install"> +<entry>remove-after-install</entry> +<entry>Overrides global</entry> +<entry><para>If you are low on hard disk space, you may want to use this option +in order to automatically delete the build directory (or both the source and +build directories for one-time installs) after the module is successfully +installed. +</para> +<para>Possible values for this option are: +<itemizedlist> +<listitem><para>none - Do not delete anything (This is the default).</para></listitem> +<listitem><para>builddir - Delete the build directory, but not the source.</para></listitem> +<listitem><para>all - Delete both the source code and build directory.</para></listitem> +</itemizedlist> +</para> + +<para>Note that using this option can have a significant detrimental impact on +both your bandwidth usage (if you use 'all') and the time taken to compile KDE, +since kdesvn-build will be unable to perform incremental builds.</para> +</entry> +</row> + +<row id="conf-set-env"> +<entry>set-env</entry> +<entry>Overrides global</entry> +<entry><para>This option accepts a space-separated set of values, where the first value +is the environment variable to set, and the rest of the values is what you +want the variable set to. For example, to set the variable RONALD to +McDonald, you would put in the appropriate section this command:</para> +<screen><command>set-env</command> <envar>RONALD</envar> <userinput>McDonald</userinput></screen> +<para>This option is special in that it can be repeated without overriding +earlier set-env settings in the same section of the configuration file. This +way you can set more than one environment variable per module (or +globally).</para> +</entry> +</row> + +<row id="conf-source-dir"> +<entry>source-dir</entry> +<entry>Can't be overridden</entry> +<entry>This option is used to set the directory on your computer to store the &kde; +&svn; sources at. If you don't specify this value, the default is +<filename class="directory">~/kdesvn</filename>. If +you do specify this value, use an absolute path name. +</entry> +</row> + +<row id="conf-svn-server"> +<entry>svn-server</entry> +<entry>Can't be overridden</entry> +<entry>This option is used to set the server used to check out from &svn;. +The default is the anonymous &svn; repository, <emphasis>svn://anonsvn.kde.org/</emphasis></entry> +</row> + +<row id="conf-stop-on-failure"> +<entry>stop-on-failure</entry> +<entry>Overrides global</entry> +<entry>Set this option value to <quote>true</quote> to cause the script to stop execution +after an error occurs during the build or install process. This option is off +by default. +</entry> +</row> + +<row id="conf-tag"> +<entry>tag</entry> +<entry>Overrides global</entry> +<entry><para>Use this option to download a specific release of a module.</para> +<para><emphasis>NOTE:</emphasis> The odds are very good that you DO NOT WANT +to use this option. KDE releases are available in tarball form from <ulink +url="ftp://ftp.kde.org/">The KDE FTP site</ulink> or one of <ulink +url="http://download.kde.org/download.php">its mirrors</ulink>.</para> +<para>If you are using kdesvn-build because you have having trouble getting +a KDE release to build on your distribution, consider using the <ulink +url="http://developer.kde.org/build/konstruct/">Konstruct build tool</ulink> +instead, which works from the release tarballs.</para> +</entry> +</row> + +<row id="conf-use-qt-builddir-hack"> +<entry>use-qt-builddir-hack</entry> +<entry>Overrides global</entry> +<entry>Although this option overrides the global option, it only makes sense for +qt-copy. Set this option to <quote>true</quote> to enable the script's +<emphasis>experimental</emphasis> srcdir != builddir mode. When enabled, +&kdesvn-build; will copy the qt-copy source module to the build directory, +and perform builds from there. That means your QTDIR environment variable +should be set to +<filename class="directory">$(qt-copy-build-dir)/qt-copy/lib</filename> +instead. You should also change your <link linkend="conf-qtdir">qtdir</link> +option accordingly. Incremental make should still work in this mode, as the +timestamps will be preserved after the copy. If you use the +<link linkend="conf-apply-qt-patches">apply-qt-patches</link> option, the patches +will be applied in the build directory, not the source directory. +This option defaults to <quote>true</quote>. +</entry> +</row> + +<row id="conf-use-unsermake"> +<entry>use-unsermake</entry> +<entry>Overrides global</entry> +<entry><para>Set this option to <quote>true</quote> in order to use the +experimental unsermake program instead of automake when running the configure +script. This can lead to some serious decreases in build time, especially for +<ulink url="http://www.csh.rit.edu/slashdot/distcc.html">distributed building +systems</ulink>. This option defaults to <quote>true</quote> (for most modules). +</para> + +<para>Normally if you use this option kdesvn-build will automatically keep +unsermake up-to-date. This may start to get annoying, especially if you are +managing unsermake yourself. If this is the case, you can set this option to +<quote>self</quote>, and kdesvn-build will still use unsermake, but will not +do anything special to keep it updated. +</para> +</entry> +</row> + +</tbody> + +</tgroup> +</table> + +</chapter> + +<chapter id="cmdline"> +<title>Command Line Options and Environment Variables</title> + +<para> +This script doesn't use environment variables. If you need to set environment +variables for the build or install process, please see the <link +linkend="conf-set-env">set-env</link> option. +</para> + +<para> +The script accepts the following command-line options: +</para> + +<variablelist> + +<varlistentry id="cmdline-help"> +<term><option>--help</option></term> +<listitem><para> +only display simple help on this script. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-version"> +<term><option>--version</option></term> +<listitem><para> +display the program version. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-author"> +<term><option>--author</option></term> +<listitem><para> +display contact information for the +author. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-color"> +<term><option>--color</option></term> +<listitem><para> +enable colorful output. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-no-color"> +<term><option>--no-color</option></term> +<listitem><para> +disable colorful output. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-pretend"> +<term><option>--pretend</option> (or <option>-p</option>)</term> +<listitem><para> +don't actually DO anything, but act like you did. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-quiet"> +<term><option>--quiet</option> (or <option>-q</option>)</term> +<listitem><para> +Don't be as noisy with the output. With this switch only the basics are +output. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-really-quiet"> +<term><option>--really-quiet</option></term> +<listitem><para> +Only output warnings and errors. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-verbose"> +<term><option>--verbose</option></term> +<listitem><para> +Be very descriptive about what's going on, and what kdesvn-build is doing. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-svn-only"> +<term><option>--svn-only</option></term> +<listitem><para> +only perform the source update. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-build-only"> +<term><option>--build-only</option></term> +<listitem><para> +only perform the build process. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-ignore-modules"> +<term><option>--ignore-modules</option></term> +<listitem><para> +don't include the modules passed on the rest of the command line in the update/build +process. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-no-svn"> +<term><option>--no-svn</option></term> +<listitem><para> +skip contacting the &svn; server. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-no-build"> +<term><option>--no-build</option></term> +<listitem><para> +skip the build process. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-no-install"> +<term><option>--no-install</option></term> +<listitem><para> +don't automatically install packages after they're built. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-debug"> +<term><option>--debug</option></term> +<listitem><para> +enables debug mode for the script. Currently +this means that all output will be dumped to STDOUT in addition to being +logged in the log directory like normal. Also, many functions are much more +verbose about what they're doing in debugging mode. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-no-rebuild-on-fail"> +<term><option>--no-rebuild-on-fail</option></term> +<listitem><para> +don't try and +rebuild modules that have failed building from scratch. &kdesvn-build; will +never try to do this to a module that already was tried to be built from +scratch. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-refresh-build"> +<term><option>--refresh-build</option></term> +<listitem><para> +recreate the build system and make from scratch. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-reconfigure"> +<term><option>--reconfigure</option></term> +<listitem><para> +run the configure script again +without cleaning the build directory. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-recreate-configure"> +<term><option>--recreate-configure</option></term> +<listitem><para> +run <command>make <option>-f</option> +Makefile.cvs</command> again to create the configure script, and continue +building as normal. This option implies <option><link linkend="cmdline-reconfigure">--reconfigure</link></option>. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-resume"> +<term><option>--resume</option></term> +<listitem><para> +which tries to continue building from where +the script stopped last time. The script starts building the module after the +last module to be compiled last time the script was run, whether or not it +succeeded. This option implies <link linkend="cmdline-no-svn"><option>--no-svn</option></link>. You +should not specify other module names on the command line. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-resume-from"> +<term><option>--resume-from</option></term> +<listitem><para> +which is like <link linkend="cmdline-resume"><option>--resume</option></link>, except that you supply +the module to start building from as the next parameter on the command line. This option +implies <link linkend="cmdline-no-svn"><option>--no-svn</option></link>. You should not specify +other module names on the command line. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-rc-file"> +<term><option>--rc-file</option></term> +<listitem><para> +which interprets the next command line +parameter as the file to read the configuration options from. The default +value for this parameter is ~/.kdesvn-buildrc. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-prefix"> +<term><option>--prefix=</path/to/kde></option></term> +<listitem><para> +which allows you to change the directory that &kde; will be installed to from the command line. +This option implies <link linkend="cmdline-reconfigure"><option>--reconfigure</option></link>. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-build-system-only"> +<term><option>--build-system-only</option></term> +<listitem><para> +stop after running <command>make <option>-f</option> Makefile.cvs</command>. The configure +script will still need to be run, which &kdesvn-build; will do next time. This lets you +prepare all the configure scripts at once so you can view the <command>./configure +<option>--help</option></command> for each module, and edit your configure-flags accordingly. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-install"><term><option>--install</option></term> +<listitem><para> +If this is the only command-line option, it tries to install all of the modules contained in +successfully-built, except for qt-copy, which doesn't need installation. If command-line +options are specified after <option>--install</option>, they are all assumed to be modules to install. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-global-option"> +<term><option>--<option-name>=</option></term> +<listitem><para> +You can use this option to override an option in your configuration file for +every module. For instance, to override the <link +linkend="conf-log-dir">log-dir</link> option, you would do: +<option>--log-dir=/path/to/dir</option>. +</para></listitem> +</varlistentry> + +<varlistentry id="cmdline-module-option"> +<term><option>--<module-name>,<option-name>=</option></term> +<listitem><para> +You can use this option to override an option in your configuration file for +a specific module. For instance, to override the <link +linkend="conf-use-unsermake">use-unsermake</link> option for kdemultimedia, you +would do: <option>--kdemultimedia,use-unsermake=false</option>. +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +Any other command-line options are assumed to be modules to update and build. +Please, don't mix building with installing. +</para> + +</chapter> + +<chapter id="credits-and-licenses"> +<title>Credits And Licenses</title> + +&underFDL; + +</chapter> + +</book> diff --git a/doc/scripts/man-adddebug.1.docbook b/doc/scripts/man-adddebug.1.docbook new file mode 100644 index 00000000..9069b486 --- /dev/null +++ b/doc/scripts/man-adddebug.1.docbook @@ -0,0 +1,66 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>March 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>addebug</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>addebug</command></refname> +<refpurpose>Modifies <filename>Makefile</filename>(s) to add debug info</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>adddebug</command> +<group><option>-k</option></group> +<group><option>-r</option></group> +<group><option>-n</option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>adddebug</command> modifies the +<filename>Makefile</filename> in the current directory (and optionally +in its subdirectories) to add debug info (<option>-g3</option>). It +will also remove optimisations (<option>-O[1-9]</option>).</para> + +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>-k</option></term> +<listitem><para>Keep optimisations (do not remove <option>-O[1-9]?</option> flags which are removed by default).</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>-r</option></term> +<listitem> +<para>Recursively search through all subdirectories of the current directory and operate on every <filename>Makefile</filename> that is found. </para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>-n</option></term> +<listitem><para>compile without NDEBUG and NO_DEBUG being defined (makes <function>kdDebug</function> calls work)</para></listitem> +</varlistentry> +</variablelist> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-cheatmake.1.docbook b/doc/scripts/man-cheatmake.1.docbook new file mode 100644 index 00000000..4fdb9498 --- /dev/null +++ b/doc/scripts/man-cheatmake.1.docbook @@ -0,0 +1,103 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<date>March 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>cheatmake</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>cheatmake</command></refname> +<refpurpose>fool <command>make</command> into not rebuilding certain files</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>cheatmake</command> + +<group><option>hidechange</option> <replaceable>file</replaceable></group> +<group><option>show</option></group> +<group><option>why</option> <replaceable>file</replaceable></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>cheatmake</command> is used to save time when +recompiling. It can fool make into skipping files that haven't changed +in a meaningful way. This can be used for instance when you change a +comment in a file but none of the actual code.</para> + +<para>This utility is part of the &kde; Software Development Kit. </para> + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>hidechange</option> <replaceable>file</replaceable></term> +<listitem><para>Hides the fact that file was changed by setting the timestamp into the past. Use with care!</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>show</option></term> +<listitem><para>Lists what files <command>make</command> currently needs to rebuild</para></listitem> +</varlistentry> +<varlistentry> +<term><option>why</option> <replaceable>file</replaceable></term> +<listitem><para>Explains why make must rebuild file</para></listitem> +</varlistentry> +</variablelist> +</refsect1> + +<refsect1> +<title>Environment</title> + +<para>One of the following variables (but not both) should be set if +the source directory is different from the build directory. If the +build directory is simply a subdirectory of the source directory, the +simpler variable <envar>OBJ_SUBDIR</envar> should be used. </para> + +<variablelist> +<varlistentry> +<term><envar>OBJ_SUBJDIR</envar></term> +<listitem><para>Indicates that the build directory is in the given subdirectory of the source directory. For instance, if the source directory is <filename class="directory">kdesdk</filename> and the build directory is <filename class="directory">kdesdk/obj-i386-linux</filename>, then <envar>OBJ_SUBDIR</envar> should be set to <parameter>obj-i386-linux</parameter>.</para></listitem> +</varlistentry> +<varlistentry> +<term><envar>OBJ_REPLACEMENT</envar></term> +<listitem><para>A <command>sed</command> expression that is used to transform the source directory into the build directory. For instance, if the source directory is <filename class="directory">kdesdk/obj-i386-linux</filename>, then <envar>OBJ_REPLACEMENT</envar> should be set to <parameter>s#kdesdk#kdesdk-obj#</parameter>.</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>make(1)</para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para><command>cheatmake</command> was written by &David.Faure; &David.Faure.mail;. This manual page was +prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email> for the Debian +<acronym>GNU</acronym>/&Linux; system (but may be used by +others).</para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-create_cvsignore.1.docbook b/doc/scripts/man-create_cvsignore.1.docbook new file mode 100644 index 00000000..1433d4ea --- /dev/null +++ b/doc/scripts/man-create_cvsignore.1.docbook @@ -0,0 +1,50 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY kdeoptions SYSTEM "kdeoptions.docbook"> +<!ENTITY qtoptions SYSTEM "qtoptions.docbook"> +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>March 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>create_cvsignore</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>create_cvsignore</command></refname> +<refpurpose>Create preliminary .cvsignore in the current directory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>createcvsignore</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>create_cvsignore</command> is used to create a +preliminary <filename>.cvsignore</filename> in the current directory. +It does this based on certain contents it finds in +<filename>Makefile.am</filename></para> + +<para>No lines will be removed from any existing +<filename>.cvsignore</filename>. If there is not already a +<filename>.cvsignore</filename> file, it will be added to the cvs +repository.</para> + +<para>Note that you must have a <filename>Makefile.am</filename> in the current directory for this tool to work.</para> + +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +</refentry>
\ No newline at end of file diff --git a/doc/scripts/man-create_makefile.1.docbook b/doc/scripts/man-create_makefile.1.docbook new file mode 100644 index 00000000..553e2512 --- /dev/null +++ b/doc/scripts/man-create_makefile.1.docbook @@ -0,0 +1,94 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY kdeoptions SYSTEM "kdeoptions.docbook"> +<!ENTITY qtoptions SYSTEM "qtoptions.docbook"> +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<date>March 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>create_makefile</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>create_makefile</command></refname> +<refpurpose>Creates <filename>Makefile.in</filename> and <filename>Makefile</filename> from a <filename>Makefile.am</filename></refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>create_makefile</command> +<group><replaceable>relativepath/Makefile</replaceable></group> +<group><replaceable>relativepath</replaceable></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>create_makefile</command> creates the +<filename>Makefile.in</filename> and <filename>Makefile</filename> in +a subdirectory containing a <filename>Makefile.am</filename>. This +script saves time compared to re-running configure completely</para> + +<para>Note that you must supply the path to the desired +<filename>Makefile</filename> <filename>Makefile.am</filename> (though +the final <filename>/Makefile</filename> may be omitted).</para> + +<para>This script may be run from the toplevel directory (the one +containing <filename>configure</filename> or from one of it's +subdirectories.</para> + +<para>If the source directory is different from the build directory +(see the environment variables below), it will be assumed that the +<filename>Makefile.am</filename> and <filename>Makefile.in</filename> +belong beneath the source directory and that the +<filename>Makefile</filename> belongs beneath the build +directory. </para> + +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>Environment</title> + +<para>One of the following variables (but not both) should be set if +the source directory is different from the build directory. If the +build directory is simply a subdirectory of the source directory, the +simpler variable <envar>OBJ_SUBDIR</envar> should be used. </para> + +<variablelist> +<varlistentry> +<term><envar>OBJ_SUBJDIR</envar></term> +<listitem><para>Indicates that the build directory is in the given subdirectory of the source directory. For instance, if the source directory is <filename class="directory">kdesdk</filename> and the build directory is <filename class="directory">kdesdk/obj-i386-linux</filename>, then <envar>OBJ_SUBDIR</envar> should be set to <parameter>obj-i386-linux</parameter>.</para></listitem> +</varlistentry> +<varlistentry> +<term><envar>OBJ_REPLACEMENT</envar></term> +<listitem><para>A <command>sed</command> expression that is used to transform the source directory into the build directory. For instance, if the source directory is <filename class="directory">kdesdk/obj-i386-linux</filename>, then <envar>OBJ_REPLACEMENT</envar> should be set to <parameter>s#kdesdk#kdesdk-obj#</parameter>.</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>create_makefiles(1)</para> +</refsect1> +<refsect1> +<title>Authors</title> + +<para>create_makefile was written by &David.Faure; &David.Faure.mail; and + others. This manual page was prepared by + <personname><firstname>Ben</firstname><surname>Burton</surname></personname> + <email>bab@debian.org</email> for the Debian GNU/Linux system (but may be + used by others).</para> +</refsect1> +</refentry> diff --git a/doc/scripts/man-create_makefiles.1.docbook b/doc/scripts/man-create_makefiles.1.docbook new file mode 100644 index 00000000..edc11159 --- /dev/null +++ b/doc/scripts/man-create_makefiles.1.docbook @@ -0,0 +1,92 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY create_makefiles "<command>create_makefiles</command>"> +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<date>March 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle>&create_makefiles;</refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname>&create_makefiles;</refname> +<refpurpose>Recreates all <filename>Makefile</filename>s beneath a directory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +&create_makefiles; +<group><replaceable>dir</replaceable></group> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para>&create_makefiles; recreates all <filename>Makefile</filename>s +in <replaceable>dir</replaceable> and its +(recursed) subdirectories from the corresponding +<filename>Makefile.am</filename> templates.</para> + +<para>This script must be run from the toplevel directory (the one +containing configure). This script saves time compared to re-running +configure completely.</para> + +<para>If the source directory is different from the build directory +(see the environment variables below), it will be assumed that each +<filename>Makefile.am</filename> and <filename>Makefile.in</filename> +belongs beneath the source directory and that each +<filename>Makefile</filename> belongs beneath the build +directory.</para> + +<para>This utility is part of the &kde; Software Development Kit.</para> +</refsect1> + + +<refsect1> +<title>Environment</title> +<para>One of the following variables (but not both) should be set if +the source directory is different from the build directory. If the +build directory is simply a subdirectory of the source directory, the +simpler variable <envar>OBJ_SUBDIR</envar> should be used. </para> + +<variablelist> +<varlistentry> +<term><envar>OBJ_SUBJDIR</envar></term> +<listitem><para>Indicates that the build directory is in the given subdirectory of the source directory. For instance, if the source directory is <filename class="directory">kdesdk</filename> and the build directory is <filename class="directory">kdesdk/obj-i386-linux</filename>, then <envar>OBJ_SUBDIR</envar> should be set to <parameter>obj-i386-linux</parameter>.</para></listitem> +</varlistentry> +<varlistentry> +<term><envar>OBJ_REPLACEMENT</envar></term> +<listitem><para>A <command>sed</command> expression that is used to transform the source directory into the build directory. For instance, if the source directory is <filename class="directory">kdesdk/obj-i386-linux</filename>, then <envar>OBJ_REPLACEMENT</envar> should be set to <parameter>s#kdesdk#kdesdk-obj#</parameter>.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>create_makefile(1) make(2)</para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para>&create_makefiles; was written by &David.Faure; &David.Faure.mail;.</para> + +<para>This manual page was prepared by +<personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email> for the Debian GNU/Linux system (but may be +used by others).</para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-cvscheck.1.docbook b/doc/scripts/man-cvscheck.1.docbook new file mode 100644 index 00000000..f2673359 --- /dev/null +++ b/doc/scripts/man-cvscheck.1.docbook @@ -0,0 +1,134 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY cvscheck "<command>cvscheck</command>"> +<!ENTITY CVS "<acronym>CVS</acronym>"> +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<date>March 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle>&cvscheck;</refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname>&cvscheck;</refname> +<refpurpose>Offline status report for files in a checked-out &CVS; module.</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +&cvscheck; +<group><replaceable>dir</replaceable></group> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para>&cvscheck; prints information about the status of your local +&CVS; checkout without communicating with the server. This means it is +extremely fast and does not require a network connection.</para> + +<para>The given directory and all of its subdirectories will be +processed recursively. If no directory is given, the current directory +and its recursed subdirectories will be used.</para> + +<para>Each file with an interesting status will be printed with a +status character in front of its name. The status characters are as +follows.</para> + +<variablelist> +<varlistentry> +<term><returnvalue>?</returnvalue> <filename>foobar.c</filename></term> +<listitem> +<para>The file is not known to &CVS;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>M</returnvalue> +<filename>foobar.c</filename></term> +<listitem> +<para>The file is definitely locally modified</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>m</returnvalue> +<filename>foobar.c</filename></term> +<listitem> +<para>The file <emphasis>might</emphasis> have local changes. You +should <command>diff</command> with the server to make sure.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>C</returnvalue> +<filename>foobar.c</filename></term> +<listitem> +<para>The file has a &CVS; conflict and therefore cannot be +committed.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>U</returnvalue> +<filename>foobar.c</filename></term> +<listitem> +<para>This file is in &CVS; but is missing in your local +checkout.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>T</returnvalue> +<filename>foobar.c</filename></term> +<listitem><para>This file has an unusual sticky &CVS; +tag.</para></listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>A</returnvalue> +<filename>foobar.c</filename></term> +<listitem> +<para>You have done a <userinput><command>cvs</command> +<option>add</option></userinput> for this file, but have not yet committed +it.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>R</returnvalue> +<filename>foobar.c</filename></term> +<listitem> +<para>You have done a <userinput><command>cvs</command> +<option>rm</option></userinput> for this file, but have not yet committed +it.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>cvs(1)</para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para>cvscheck was written by &Dirk.Mueller; &Dirk.Mueller.mail; + and Sirtaj.Singh.Kang; &Sirtaj.Singh.Kang.mail;</para> + +<para>This manual page was prepared by +<personname><firstname>Ben</firstname> +<surname>Burton</surname></personname> <email>bab@debian.org</email> for the +Debian GNU/Linux system (but may be used by others). + </para> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-cvslastchange.1.docbook b/doc/scripts/man-cvslastchange.1.docbook new file mode 100644 index 00000000..eb86d966 --- /dev/null +++ b/doc/scripts/man-cvslastchange.1.docbook @@ -0,0 +1,52 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY cvslastchange "<command>cvslastchange</command>"> +<!ENTITY CVS "<acronym>CVS</acronym>"> +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>March 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle>&cvslastchange;</refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname>&cvslastchange;</refname> +<refpurpose>Display the last change committed to &CVS; for a file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +&cvslastchange; +<group><replaceable>file</replaceable></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para>&cvslastchange; displays the last change committed to &CVS; for +a file. It uses <command>cvs diff</command> and <command>cvs +log</command> to do this.</para> + +<para>&cvslastchange; works on any &CVS; branch, not just HEAD.</para> + +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>cvslastlog(1) cvsrevertlast(1) cvs(1)</para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-cvslastlog.1.docbook b/doc/scripts/man-cvslastlog.1.docbook new file mode 100644 index 00000000..ed59f426 --- /dev/null +++ b/doc/scripts/man-cvslastlog.1.docbook @@ -0,0 +1,42 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email></email></author> +<date>April 06, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>cvslastlog</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>cvslastlog</command></refname> +<refpurpose>Prints the log entry for the last commit for a file.</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>cvslastlog</command> + +<group><option><replaceable>filename</replaceable></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>cvslastlog</command> shows the log associated with the +last CVS commit for the given file. It depends on the version of the +local file, not the one on the server. </para> + +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-cvsrevertlast.1.docbook b/doc/scripts/man-cvsrevertlast.1.docbook new file mode 100644 index 00000000..8af8d658 --- /dev/null +++ b/doc/scripts/man-cvsrevertlast.1.docbook @@ -0,0 +1,48 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email></email></author> +<date>Month Daynumber, 4-Digit-Year</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>cvsrevertlast</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>cvsrevertlast</command></refname> +<refpurpose>Revert files in CVS by one version</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>cvsrevertlast</command> + +<group><option><replaceable>filename</replaceable></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para>cvsrevertlast is used to revert all the files on the command +line by one version in CVS. The files will not be committed.</para> + +<para>This utility is part of the KDE Software Development Kit. </para> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>cvsblame(1)</para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-cxxmetric.1.docbook b/doc/scripts/man-cxxmetric.1.docbook new file mode 100644 index 00000000..f37d4a7c --- /dev/null +++ b/doc/scripts/man-cxxmetric.1.docbook @@ -0,0 +1,43 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>April 07, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>cxxmetric</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>cxxmetric</command></refname> +<refpurpose>Simple source metrics for C and C++</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>cxxmetric</command> + +<group><option><replaceable>file</replaceable></option></group> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para>cxxmetric counts lines of code, comment and blank space and +calculates various other statistics for each given source file. Source +files must be in C or C++.</para> + +<para>This utility is part of the KDE Software Development Kit. </para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-demangle.1.docbook b/doc/scripts/man-demangle.1.docbook new file mode 100644 index 00000000..40043252 --- /dev/null +++ b/doc/scripts/man-demangle.1.docbook @@ -0,0 +1,63 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>demangle</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>demangle</command></refname> +<refpurpose>Undo C++ name mangling for symbols</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>demangle</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>demangle</command> reads a list of C++ mangled symbol names from standard input and converts these names to human-readable form on standard output.</para> + +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>Example</title> + +<para>Create a file called <filename>names</filename> containing the following mangled symbol names:</para> + +<programlisting>_ZNK6Object10metaObjectEv +_ZN8QPtrListI5ArrowE5clearEv +_ZTC4Kolf0_11KMainWindow</programlisting> + +<para>These names can then be demangled as follows:</para> + +<screen><prompt>example$</prompt> <userinput><command>demangle</command> < <filename>names</filename></userinput> +<computeroutput>Object::metaObject() const +QPtrList<Arrow>::clear() +construction vtable for KMainWindow-in-Kolf</computeroutput></screen> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>kminspector(1) kmtrace(1) match(1)</para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-extend_dmalloc.1.docbook b/doc/scripts/man-extend_dmalloc.1.docbook new file mode 100644 index 00000000..ef85d1f8 --- /dev/null +++ b/doc/scripts/man-extend_dmalloc.1.docbook @@ -0,0 +1,54 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>extend_dmalloc</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>extend_dmalloc</command></refname> +<refpurpose>Analyze return-addresses from dmalloc logfiles.</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>extend_dmalloc</command> +<group><option><replaceable>dmalloc-log</replaceable> <command>binary</command></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>extend_dmalloc</command> will run <command>gdb</command>(1) to get information on the return-addresses from a <command>dmalloc</command>(1) logfile. Specifically it will examine any <literal>ra=</literal> lines and try to get the corresponding line numbers</para> + +<para>The argument +<option><command>binary</command></option> +must be the binary that generated the log +<filename>dmalloc-log</filename>.</para> + +<para>This utility is part of the &kde; Software Development +Kit.</para> + +</refsect1> + + +<refsect1> +<title>Notes</title> +<para>You may wish to direct the output from +<command>extend_dmalloc</command> to a file, since otherwise +<command>gdb</command> seems to prompt for a return as if you are at +the end of a page. </para> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-extractrc.1.docbook b/doc/scripts/man-extractrc.1.docbook new file mode 100644 index 00000000..6739c4a1 --- /dev/null +++ b/doc/scripts/man-extractrc.1.docbook @@ -0,0 +1,46 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>extractrc</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>extractrc</command></refname> +<refpurpose>Extract message strings from UI and GUI-RC files</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>extractrc</command> + +<group><option><replaceable>filename</replaceable></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>extractrc</command> finds all text tags and other +message strings in the given files and writes the corresponding i18n() +calls to standard output so that xgettext can parse them.</para> + +<para>It understands both (&Qt;/&kde;) +<application>designer</application>'s <acronym>UI</acronym> files and +&XML; GUI-RC files. </para> + +<para>This utility is part of the KDE Software Development Kit. </para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-fixincludes.1.docbook b/doc/scripts/man-fixincludes.1.docbook new file mode 100644 index 00000000..a4850ddc --- /dev/null +++ b/doc/scripts/man-fixincludes.1.docbook @@ -0,0 +1,98 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>fixincludes</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>fixincludes</command></refname> +<refpurpose>Reduce the number of #includes in &kde; source files</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>fixincludes</command> +<group><option>-v, --verbose</option></group> +<group><option>-e, --experimental</option></group> +<group><option>-m, --modify</option></group> +<group><option><replaceable>file</replaceable></option></group> +<group><option>--help</option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>fixincludes</command> tries to reduce the number of +#includes in C++ source files. Much of it's processing is specific to +&kde; sources and so it might not work so well with sources for +non-&kde; applications.</para> + +<para>The following problems are identified by <command>fixincludes</command>:</para> + +<itemizedlist> +<listitem> +<para>Including headers that are no longer supported but which exist for compatibility with older Qt/KDE versions;</para> +</listitem> +<listitem> +<para>Including the same file multiple times. </para> +</listitem> +</itemizedlist> + +<para>There is also an experimental mode which tries removing each +#include one at a time (with a few exceptions) to see whether the +source still compiles. Note that this experimental mode will modify +the original sources. </para> + +<para>By default the sources will not be modified; the identified +problems will simply be written to standard output. </para> + +<para>The list of C++ sources to examine should be given on the +command-line. If no files are given, all C++ sources in or beneath the +current directory will be examined (with the exception of directories +whose <filename>Makefile.am</filename> contains +<option>-UQT_NO_COMPAT</option> or +<option>-UKDE_NO_COMPAT</option>)</para> + +<para>This utility is part of the KDE Software Development Kit. </para> + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>-v, --verbose</option></term> +<listitem><para>Verbose mode. Additional debugging output is written to standard output.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-e, --experimental</option></term> +<listitem><para>Experimental mode, as described above in detail. Note that this option implies <option>--modify</option>.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-m, --modify</option></term> +<listitem><para>As well as writing messages to standard output, actually modify the original sources to fix any problems that were found.</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>Authors</title> +<para><command>fixincludes</command> was written by Dirk Mueller <email>mueller@kde.org</email>. +</para> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-po2xml.1.docbook b/doc/scripts/man-po2xml.1.docbook new file mode 100644 index 00000000..d9fbd2ff --- /dev/null +++ b/doc/scripts/man-po2xml.1.docbook @@ -0,0 +1,58 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email>bab@debian.org</email></author> +<date>April 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>po2xml</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>po2xml</command></refname> +<refpurpose>Translates an DocBook XML file using a PO file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>po2xml</command> + +<group><option><replaceable>original-XML</replaceable> <replaceable>translated-PO</replaceable></option></group> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>po2xml</command> is a command-line tool that translates +the DocBook XML file <replaceable>original-XML</replaceable> using the +gettext message file <replaceable>translated-PO</replaceable>. The +resulting translated XML file is sent to standard output.</para> + +<para>This utility is part of the KDE Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>split2po(1), swappo(1), transxx(1), xml2pot(1)</para> + +</refsect1> + +<refsect1> +<title>Authors</title> +<para>The PO-XML tools were written by &Stephan.Kulow; &Stephan.Kulow.mail;</para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-pruneemptydirs.1.docbook b/doc/scripts/man-pruneemptydirs.1.docbook new file mode 100644 index 00000000..ee5046a7 --- /dev/null +++ b/doc/scripts/man-pruneemptydirs.1.docbook @@ -0,0 +1,69 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></author> +<date>April 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>pruneemptydirs</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>pruneemptydirs</command></refname> +<refpurpose>Detects stale source directories in a CVS tree</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>pruneemptydirs</command> +<group><option>-f</option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>pruneemptydirs</command> is used to clean up a local +CVS tree. It detects directories containing remnants of old stuff +which has been removed from the CVS. Such stale directories often +break compilation. The current directory and all directories beneath +it will be examined.</para> + +<para>Note that this tool does not remove anything; it simply prints +what to do as a series of remove commands. You can copy and paste +these commands, or use them with eval in a script.</para> + +<para>This tool works better if the source directory is not the same +as the build directory, since it will not print directories containing +old executables.</para> + +<para>This utility is part of the KDE Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>-f</option></term> +<listitem><para>Actually perform the deletions instead of just printing them out. Use this option with care.</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para><command>pruneemptydirs</command> was written by &David.Faure; &David.Faure.mail;</para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-qtdoc.1.docbook b/doc/scripts/man-qtdoc.1.docbook new file mode 100644 index 00000000..7491089e --- /dev/null +++ b/doc/scripts/man-qtdoc.1.docbook @@ -0,0 +1,75 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></author> +<date>April 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>qtdoc</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>qtdoc</command></refname> +<refpurpose>Open a &Qt; help page in &konqueror;</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>qtdoc</command> + +<group><option><replaceable>classname</replaceable></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>qtdoc</command> opens a &Qt; help page in &konqueror;. +If <replaceable>classname</replaceable> is given, it opens the help +page for that class. Otherwise the main &Qt; help page is opened. +<replaceable>classname</replaceable> is case insensitive.</para> + +<para>This utility is part of the &kde; Software Development Kit</para> + +</refsect1> + +<refsect1> +<title>Environment</title> + +<variablelist> +<varlistentry> +<term><envar>QTDIR</envar></term> +<listitem><para>The directory beneath which &Qt; is installed. The main &Qt; help page is expected to be in <filename class="directory">$<envar>QTDIR</envar>/doc/html/</filename>.</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>Examples</title> + +<para>To display the help on the class <classname>QString</classname>:</para> +<screen><userinput><command>qtdoc</command> <option>QString</option></userinput></screen> +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>kdedoc(1), assistant(1)</para> + +</refsect1> + + +<refsect1> +<title>Authors</title> + +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-reportview.1.docbook b/doc/scripts/man-reportview.1.docbook new file mode 100644 index 00000000..9e050567 --- /dev/null +++ b/doc/scripts/man-reportview.1.docbook @@ -0,0 +1,73 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY Ian.Reinhart.Geiser "<personname><firstname>Ian</firstname><othername>Reinhart</othername><surname>Geiser</surname></personname>"> +<!ENTITY Ian.Reinhart.Geiser.mail "<email>geiseri@kde.org</email>"> +<!ENTITY kweather "<application>kweather</application>"> +<!ENTITY Nadeem.Hasan "<personname><firstname>Nadeem</firstname><surname>Hasan</surname></personname>"> +<!ENTITY Nadeem.Hasan.mail "<email>nhasan@kde.org</email>"> +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>reportview</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>reportview</command></refname> +<refpurpose>ask KWeatherService to display a weather report </refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>reportview;</command> +<group><option>KDE Generic Options</option></group> +<group><option>Qt Generic Options</option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>reportview</command> is not intended to be used +directly.</para> + +<para><command>reportview</command> is a small program that asks +KWeatherService to display a weather report. Information shown +includes the temperature, wind speed and air pressure.</para> + +<para>KWeatherService is a DCOP service used by both reportview and +the &kweather; panel applet to provide weather data. There is no need to +start KWeatherService separately; reportview will start the service +itself if needed.</para> + +</refsect1> + + +<refsect1> +<title>See Also</title> + +<para>kweather(1)</para> + +<para>More detailed user documentation is available from <ulink +url="help:/kweather">help:/kweather</ulink> (either enter this +<acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kweather</parameter></userinput>).</para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para>&kweather; was written by &Ian.Reinhart.Geiser; &Ian.Reinhart.Geiser.mail; and &Nadeem.Hasan; &Nadeem.Hasan.mail;</para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-split2po.1.docbook b/doc/scripts/man-split2po.1.docbook new file mode 100644 index 00000000..c2823b39 --- /dev/null +++ b/doc/scripts/man-split2po.1.docbook @@ -0,0 +1,64 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>split2po</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>split2po</command></refname> +<refpurpose>Creates a po file from two DocBook XML files</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>split2po</command> +<group choice="req"><option><replaceable>Original-XML</replaceable></option> +<option><replaceable>Translated-XML</replaceable></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>split2po</command> is a command-line tool that +takes the two given DocBook XML files and produces a +<command>gettext</command> message file (PO-file) that represents the +changes between them. The resulting PO-file is sent to standard +output.</para> + +<para><filename>translated-XML</filename> must be the result of +translating <filename>original-XML</filename> into another +language. It is this translation that the resulting PO-file will +represent.</para> + +<para>This utility is part of the KDE Software Development Kit. </para> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>po2xml(1), swappo(1), transxx(1), xml2pot(1)</para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para>The PO XML tools were written by &Stephan.Kulow; +&Stephan.Kulow.mail;</para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-swappo.1.docbook b/doc/scripts/man-swappo.1.docbook new file mode 100644 index 00000000..8df1f492 --- /dev/null +++ b/doc/scripts/man-swappo.1.docbook @@ -0,0 +1,59 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>swappo</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>swappo</command></refname> +<refpurpose>swap msgid and msgstr fields in a PO file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>swappo</command> + +<group><option><replaceable>filename.po</replaceable></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>swappo</command> reads the given PO-file and swaps the +msgid and msgstr fields for every message. The result is a new PO-file +that translates in the opposite direction. For example, if PO-file +translates from English to French, the new PO-file will translate from +French to English.</para> + +<para>The new PO-file will be written to standard output. The old PO-file will remain untouched.</para> + +<para>This utility is part of the &kde; Software Development Kit</para> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>po2xml(1), split2po(1), transxx(1), xml2pot(1)</para> + +</refsect1> + +<refsect1> +<title>Authors</title> +<para>The PO-XML tools were written by &Stephan.Kulow; &Stephan.Kulow.mail;</para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> + +</refsect1> + +</refentry> diff --git a/doc/scripts/man-transxx.1.docbook b/doc/scripts/man-transxx.1.docbook new file mode 100644 index 00000000..629c6d1c --- /dev/null +++ b/doc/scripts/man-transxx.1.docbook @@ -0,0 +1,55 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>transxx</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>transxx</command></refname> +<refpurpose>Create a pseudo translated PO file from a PO template file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>transxx</command> +<group><option><replaceable>template.pot</replaceable></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>transxx</command> is a command-line tool that produces +a basic fleshed-out PO-file from a PO-template file. Some of the +formatting and structure of the msgid strings will be copied to the +msgstr strings, but otherwise text will be translated to +<quote>xx</quote>.</para> + +<para>The fleshed-out PO-file is sent to standard output.</para> + +<para>Running your software with the language <quote>xx</quote> will +quickly show you any user visible strings that are not +translateable.</para> + +<para>This utility is part of the KDE Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para>The PO-XML tools were written by &Stephan.Kulow; &Stephan.Kulow.mail;</para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-xml2pot.1.docbook b/doc/scripts/man-xml2pot.1.docbook new file mode 100644 index 00000000..01964972 --- /dev/null +++ b/doc/scripts/man-xml2pot.1.docbook @@ -0,0 +1,63 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>xml2pot</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>xml2pot</command></refname> +<refpurpose>Creates a PO template file from a DocBook XML file.</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>xml2pot</command> + +<group><option><replaceable>original-XML</replaceable></option></group> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>xml2pot</command> is a command-line tool that produces +a gettext message template file from the DocBook XML file +<filename>original-XML</filename>. The template file is sent to +standard output.</para> + +<para>The resulting template file can be used to create gettext +message files (PO-files) for a variety of languages. These can then be +used in conjunction with <command>po2xml</command>(1) to translate the +original XML file into these other languages.</para> + + +<para>This utility is part of the KDE Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>po2xml(1), split2po(1), swappo(1), transxx(1)</para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para>The PO XML tools were written by &Stephan.Kulow; &Stephan.Kulow.mail;</para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> +</refsect1> + +</refentry> diff --git a/doc/scripts/man-zonetab2pot.1.docbook b/doc/scripts/man-zonetab2pot.1.docbook new file mode 100644 index 00000000..308e7638 --- /dev/null +++ b/doc/scripts/man-zonetab2pot.1.docbook @@ -0,0 +1,56 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> +<email></email></author> +<date>April 7, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>zonetab2pot.py</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>zonetab2pot.py</command></refname> +<refpurpose>Converts a timezone list to a PO file template.</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>zonetab2pot.py</command> + +<group><option><replaceable>timezone-list</replaceable></option></group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><command>zonetab2pot.py</command> reads the timezone list given +on the command-line and converts it to a gettext message file +(PO-file) template containing the names of the individual +timezones. </para> + +<para>The given timezone list should be in the same format as the system +zone.tab. If no timezone list is specified on the command-line, +<filename>/usr/share/zoneinfo/zone.tab</filename> will be used.</para> + +<para>The new PO-file template will be written to standard output.</para> + +<para>This utility is part of the KDE Software Development Kit. </para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para>zonetab2pot.py was written by <personname><firstname>Lukas</firstname><surname>Tinkl</surname></personname><email>lukas@kde.org</email></para> +<para>This manual page was prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname><email>bab@debian.org</email></para> +</refsect1> + +</refentry> diff --git a/doc/umbrello/Makefile.am b/doc/umbrello/Makefile.am new file mode 100644 index 00000000..45fb6fde --- /dev/null +++ b/doc/umbrello/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = umbrello diff --git a/doc/umbrello/activity-diagram.png b/doc/umbrello/activity-diagram.png Binary files differnew file mode 100644 index 00000000..75234476 --- /dev/null +++ b/doc/umbrello/activity-diagram.png diff --git a/doc/umbrello/add-remove-languages.png b/doc/umbrello/add-remove-languages.png Binary files differnew file mode 100644 index 00000000..42c1d908 --- /dev/null +++ b/doc/umbrello/add-remove-languages.png diff --git a/doc/umbrello/aggregation.png b/doc/umbrello/aggregation.png Binary files differnew file mode 100644 index 00000000..46050842 --- /dev/null +++ b/doc/umbrello/aggregation.png diff --git a/doc/umbrello/association.png b/doc/umbrello/association.png Binary files differnew file mode 100644 index 00000000..ac984111 --- /dev/null +++ b/doc/umbrello/association.png diff --git a/doc/umbrello/authors.docbook b/doc/umbrello/authors.docbook new file mode 100644 index 00000000..1a079f02 --- /dev/null +++ b/doc/umbrello/authors.docbook @@ -0,0 +1,41 @@ +<chapter id="authors"> +<title>Authors and History</title> +<para> +This project was started by Paul Hensgen as one of his University projects. +The original name of the application was <application>UML Modeller</application>. Paul did +all the development until the end of 2001 when the program reached version 1.0. +</para> +<para> +Version 1.0 already offered a lot of functionality, but after the project had been reviewed at +Paul's University, other developers could join and they started making valuable contributions +to <application>UML Modeller</application>, like switching from a binary file format to an &XML; file, support for more +types of &UML; Diagrams, Code Generation and Code Import just to name a few. +</para> +<para> +Paul had to retire from the development team in Summer 2002 but, as Free and Open Source Software, the +program continues to improve and evolve and is being maintained by a group of developers from different +parts of the world. In September 2002 the project changed its name from <application>&UML; Modeller</application>, to +&umbrello;. There are several reasons for the change of names, the most +important ones being that just <quote>uml</quote> — as it was commonly known — was a much too generic name +and caused problems with some distributions. The other important reason is that the developers think +<application>Umbrello</application> is a much cooler name. +</para> +<para> +The development of &umbrello; as well as discussions as to where the program should head for future versions +is open and takes place over the Internet. If you would like to contribute to the project, please do not +hesitate to contact the developers. There are many ways in which you can help &umbrello;: +</para> +<itemizedlist> +<listitem><para>Reporting bugs or improvements suggestions</para></listitem> +<listitem><para>Fixing bugs or adding features</para></listitem> +<listitem><para>Writing good documentation or translating it to other languages</para></listitem> +<listitem><para>And of course...coding with us!</para></listitem> +</itemizedlist> +<para> +As you see, there are many ways in which you can contribute. All of them are very important and +everyone is welcome to participate. +</para> +<para> +The &umbrello; developers can be reached at <email>uml-devel@lists.sourceforge.net</email>. +</para> +</chapter> diff --git a/doc/umbrello/class-diagram.png b/doc/umbrello/class-diagram.png Binary files differnew file mode 100644 index 00000000..3b12a4f6 --- /dev/null +++ b/doc/umbrello/class-diagram.png diff --git a/doc/umbrello/class.png b/doc/umbrello/class.png Binary files differnew file mode 100644 index 00000000..9c12a849 --- /dev/null +++ b/doc/umbrello/class.png diff --git a/doc/umbrello/code-import.png b/doc/umbrello/code-import.png Binary files differnew file mode 100644 index 00000000..49f477e5 --- /dev/null +++ b/doc/umbrello/code-import.png diff --git a/doc/umbrello/code_import_and_generation.docbook b/doc/umbrello/code_import_and_generation.docbook new file mode 100644 index 00000000..8beffcc3 --- /dev/null +++ b/doc/umbrello/code_import_and_generation.docbook @@ -0,0 +1,170 @@ +<chapter id="code-import-generation"> +<title>Code Import and Code Generation</title> +<para> +&umbrello; is a &UML; modelling tool, and as such its main purpose is to help you in the +<emphasis>analysis and design</emphasis> of your systems. However, to make the transition +between your design and your <emphasis>implementation</emphasis>, &umbrello; allows you to +generate source code in different programming languages to get you started. Also, if you +want to start using &UML; in an already started C++ project, &umbrello; can help you create a model +of your system from the source code by analysing your source code and importing the classes +found in it. +</para> +<sect1 id="code-generation"> +<title>Code Generation</title> +<para> +&umbrello; can generate source code for various programming languages based on your &UML; Model +to help you get started with the implementation of your project. The code generated consists +of the class declarations, with their methods and attributes so you can <quote>fill in the +blanks</quote> by providing the functionality of your classes' operations. +</para> +<para> +&umbrello; 1.2 comes with code generation support for ActionScript, Ada, C++, CORBA IDL, &Java;, JavaScript, <acronym>PHP</acronym>, Perl, Python, SQL and XMLSchema. +</para> +<sect2 id="generate-code"> +<title>Generating Code</title> +<para> +In order to generate code with &umbrello;, you first need to create or load a Model +containing at least one class. When you are ready to start writing some code, select the +<guimenuitem>Code Generation Wizard</guimenuitem> entry from the <guimenuitem>Code</guimenuitem> menu to +start a wizard which will guide you trough the code generation process. +</para> +<para> +The first step is to select the classes for which you want to generate source code. +By default all the classes of your model are selected, and you can remove the ones +for which you do not want to generate code by moving them to the left-hand side list. +</para> +<para> +The next step of the wizard allows you to modify the parameters the Code Generator uses +while writing your code. The following options are available: +</para> +<para> +<screenshot> +<screeninfo>Code Generation Options</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="generation-options.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Options for the Code Generation in &umbrello;</phrase> + </textobject> + <caption> + <para>Options for the Code Generation in &umbrello; + </para> + </caption> + </mediaobject> +</screenshot> +</para> +<sect3 id="generation-options"> +<title>Generation Options</title> +<!-- LW; to rearrange --> + +<sect4> +<title>Code Verbosity</title> +<para> +The option <guilabel>Write documentation comments even if empty</guilabel> instructs the + Code Generator to write comments of the /** blah */ style even if the comment blocks are empty. +If you added documentation to your classes, methods or attributes in your Model, the +Code Generator will write these comments as <application>Doxygen</application> documentation regardless of what you set here, but +if you select this option &umbrello; will write comment blocks for all classes, methods and attributes +even if there is no documentation in the Model, in which case you should document your classes +later directly in the source code. +</para> +<para> +<guilabel>Write comments for sections even if section is empty</guilabel> causes &umbrello; to write comments +in the source code to delimit the different sections of a class. For example <quote>public methods</quote> + or <quote>Attributes</quote> before the corresponding sections. If you select this option &umbrello; + will write comments for all sections of the class even if the section is empty. For example, + it would write a comment saying <quote>protected methods</quote> even if there are no protected + methods in your class. +</para> +</sect4> +<sect4> +<title>Folders</title> +<para> +<guilabel>Write all generated files to folder</guilabel>. Here you should select the folder +where you want &umbrello; to put the generated sources. +</para> +<para> +The <guilabel>Include heading files from folder</guilabel> option allows you to insert a +heading at the beginning of each generated file. Heading files can contain copyright or licensing + information and contain variables that are evaluated at generation time. You can take a look + at the template heading files shipped with &umbrello; to see how to use this variables for replacing + your name or the current date at generation time. +</para> +</sect4> +<sect4> +<title>Overwrite Policy</title> +<!-- FIXME update for Umbrello 1.2's new C++ and Java code generators --> +<para> +This option tells &umbrello; what to do if the file it wants to create already exists in +the destination folder. &umbrello; <emphasis>cannot modify existing source files</emphasis>, +so you have to choose between overwriting the existing file, skipping the generation of +that particular file or letting &umbrello; choose a different file name. If you choose the option +to use a different name, &umbrello; will add a suffix to the file name. +</para> +</sect4> +<sect4> +<title>Language</title> +<para> +&umbrello; will by default generate code in the language you have selected as Active Language, but +with the Code Generation Wizard you have the option to change this to another language. +</para> +</sect4> +</sect3><!--generation-options--> +<sect3 id="generation-wizard-generation"> +<title>Generation Wizard Generation</title> +<para> +The third and last step of the wizard shows the status of the Code Generation process. +You need only to click on the Generate button to get your classes written for you. +</para> +<para> +Note that the Options you select during the Code Generation Wizard are only valid for the current +generation. The next time you run the wizard you will need to re-select all the options +(your headings folder, overwrite policy, and so on). You can set the defaults used by &umbrello; +in the <guilabel>Code Generation</guilabel> section of the &umbrello; settings, available +at <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &umbrello;...</guimenuitem></menuchoice> +</para> +<para> +If you have set your Code Generation options to the right settings and want to generate +some code right away without going through the wizard, you can select the entire +<guimenuitem>Generate All Code</guimenuitem> from the Code menu. +This will generate code for all the classes in your Model using the current settings +(including Output Folder and Overwrite Policy, so use with care). +</para> +</sect3> +</sect2><!--generate-code--> +</sect1> <!--code-generation--> +<sect1 id="code-import"> +<title>Code Import</title> +<para> +&umbrello; can import source code from your existing projects to help you build Model of +your systems. &umbrello; 1.2 supports only C++ source code, but other languages +should be available in future versions. +</para> +<para> +To import classes into your Model, select the entry <guimenuitem>Import Classes...</guimenuitem> from +the <guimenu>Code</guimenu> menu. In the file dialog select the files containing the C++ +class declarations and press OK. The classes will be imported and you will find them as part of +your Model in the Tree View. Note that &umbrello; will not create any kind of Diagram for showing +your classes, they will only be imported into your Model so that you can use them later in any +diagram you want. +</para> +<para> +<screenshot> +<screeninfo>Code Import</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="code-import.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Menu for importing source code in &umbrello;</phrase> + </textobject> + <caption> + <para>Menu for importing source code in &umbrello; + </para> + </caption> + </mediaobject> +</screenshot> +</para> +</sect1> +</chapter> <!--code-import-generation--> diff --git a/doc/umbrello/collaboration-diagram.png b/doc/umbrello/collaboration-diagram.png Binary files differnew file mode 100644 index 00000000..681d5c77 --- /dev/null +++ b/doc/umbrello/collaboration-diagram.png diff --git a/doc/umbrello/composition.png b/doc/umbrello/composition.png Binary files differnew file mode 100644 index 00000000..ad07e1d9 --- /dev/null +++ b/doc/umbrello/composition.png diff --git a/doc/umbrello/credits.docbook b/doc/umbrello/credits.docbook new file mode 100644 index 00000000..807089a5 --- /dev/null +++ b/doc/umbrello/credits.docbook @@ -0,0 +1,12 @@ +<chapter id="copyright"> +<title>Copyright</title> + +<para>Copyright 2001, Paul Hensgen</para> +<para>Copyright 2002, 2003 The &umbrello; Authors. See +<ulink url="http://uml.sf.net/developers.php">http://uml.sf.net/developers.php</ulink> +for more information</para> + +&underFDL; +&underGPL; + +</chapter> diff --git a/doc/umbrello/folders.png b/doc/umbrello/folders.png Binary files differnew file mode 100644 index 00000000..59680d97 --- /dev/null +++ b/doc/umbrello/folders.png diff --git a/doc/umbrello/generalization.png b/doc/umbrello/generalization.png Binary files differnew file mode 100644 index 00000000..8236cca3 --- /dev/null +++ b/doc/umbrello/generalization.png diff --git a/doc/umbrello/generation-options.png b/doc/umbrello/generation-options.png Binary files differnew file mode 100644 index 00000000..37c05697 --- /dev/null +++ b/doc/umbrello/generation-options.png diff --git a/doc/umbrello/index.docbook b/doc/umbrello/index.docbook new file mode 100644 index 00000000..0da7c91e --- /dev/null +++ b/doc/umbrello/index.docbook @@ -0,0 +1,69 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" + "dtd/kdex.dtd" [ + <!ENTITY umbrello "<application>Umbrello &UML; Modeller</application>"> + <!ENTITY kappname "&umbrello;"> + <!ENTITY packagename "kdesdk"> + <!ENTITY UML "<acronym>UML</acronym>"> + <!ENTITY introduction-chapter SYSTEM "introduction.docbook"> + <!ENTITY uml-basics-chapter SYSTEM "uml_basics.docbook"> + <!ENTITY working-with-umbrello-chapter SYSTEM "working_with_umbrello.docbook"> + <!ENTITY code-import-and-generation-chapter SYSTEM "code_import_and_generation.docbook"> + <!ENTITY other-features-chapter SYSTEM "other_features.docbook"> + <!ENTITY authors-chapter SYSTEM "authors.docbook"> + <!ENTITY credits-chapter SYSTEM "credits.docbook"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> + <!-- Do not define any other entities; instead, use the entities + from kde-genent.entities and $LANG/user.entities. --> +]> + +<book id="Umbrello" lang="&language;"> +<bookinfo> +<title>&umbrello; Handbook</title> + +<authorgroup> +<corpauthor>&umbrello; Authors</corpauthor> +</authorgroup> + +<copyright> +<year>2001</year> +<holder>Paul Hensgen</holder> +</copyright> +<copyright> +<year>2002, 2003</year> +<holder>&umbrello; Authors</holder> +</copyright> + + +<date>2003-10-15</date> +<releaseinfo>1.2</releaseinfo> + +<abstract> +<para> +&umbrello; helps the software development +process by using the industry standard Unified Modelling Language (&UML;) +to enable you to create diagrams for designing and documenting your systems. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>UML</keyword> +<keyword>modelling</keyword> +<keyword>diagrams</keyword> +<keyword>software development</keyword> +<keyword>development</keyword> +</keywordset> + +</bookinfo> + +&introduction-chapter; +¨-basics-chapter; +&working-with-umbrello-chapter; +&code-import-and-generation-chapter; +&other-features-chapter; +&authors-chapter; +&credits-chapter; + +</book> diff --git a/doc/umbrello/introduction.docbook b/doc/umbrello/introduction.docbook new file mode 100644 index 00000000..3af9f719 --- /dev/null +++ b/doc/umbrello/introduction.docbook @@ -0,0 +1,43 @@ +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&umbrello; is a &UML; diagram tool that can support you +in the software development process. +Especially during the analysis and design phases of this process, &umbrello; will help you to +get a high quality product. &UML; can also be used to document your software designs to help you and your +fellow developers. +</para> +<para> +Having a good model of your software is the best way to communicate with +other developers working on the project and with your customers. A good model +is extremely important for medium and big-size projects, but it is also very useful +for small ones. Even if you are working on a small one man project you +will benefit from a good model because it will give you an overview that will help +you code things right the first time. +</para> +<para> +&UML; is the diagramming language used to describing such models. You can represent your ideas in &UML; +using different types of diagrams. &umbrello; 1.2 supports the following types: +</para> +<itemizedlist> +<listitem><para>Class Diagram</para></listitem> +<listitem><para>Sequence Diagram</para></listitem> +<listitem><para>Collaboration Diagram</para></listitem> +<listitem><para>Use Case Diagram</para></listitem> +<listitem><para>State Diagram</para></listitem> +<listitem><para>Activity Diagram</para></listitem> +<listitem><para>Component Diagram</para></listitem> +<listitem><para>Deployment Diagram</para></listitem> +</itemizedlist> +<para> +More information about &UML; can be found at the website of +<ulink url="http://www.omg.org"><acronym>OMG</acronym>, http://www.omg.org</ulink> who create the &UML; standard. +</para> +<para> +We hope you enjoy &umbrello; and that it helps you create high quality software. +&umbrello; is Free Software and available at no cost, the only thing we ask from you is to report any bugs, problems, or suggestions +to the &umbrello; developers at <email>uml-devel@lists.sourceforge.net</email> or +<ulink url="http://bugs.kde.org">http://bugs.kde.org</ulink>. +</para> +</chapter> diff --git a/doc/umbrello/other_features.docbook b/doc/umbrello/other_features.docbook new file mode 100644 index 00000000..1f368622 --- /dev/null +++ b/doc/umbrello/other_features.docbook @@ -0,0 +1,61 @@ +<chapter id="other-features"> +<title>Other Features</title> +<sect1> +<title>Other &umbrello; Features</title> +<para>This chapter will briefly explain some other features &umbrello; offers you.</para> +<sect2 id="copying-as-png"> +<title>Copying objects as PNG images</title> +<para> +Apart from offering you the normal copy, cut and paste functionality that you would expect to copy +objects between different diagrams, &umbrello; can copy the objects as PNG pictures so that you can +insert them into any other type of document. You do not need to do anything special to use this feature, +just select an object from a diagram (Class, Actor, &etc;) and copy it (<keycombo>&Ctrl;<keycap>C</keycap></keycombo>, + or using the menu), then open a &kword; document (or any program into which you can paste images) and select <guimenuitem>Paste</guimenuitem>. This is a great feature +to export parts of your diagram as simple pictures. +</para> +</sect2> +<sect2 id="export-as-png"> +<title>Exporting to an Image</title> +<para> +You can also export a complete diagram as an image. The only thing you need to do is select +the diagram you want to export, and then the option <guimenuitem>Export as Picture...</guimenuitem> from +the <guimenu>Diagram</guimenu> menu. +</para> +</sect2> +<sect2 id="printing"> +<title>Printing</title> +<para> +&umbrello; allows you to print individual diagrams. Press the <guiicon>Print</guiicon> button on the + application toolbar or selecting the <guimenuitem>Print</guimenuitem> option from the +<guimenu>File</guimenu> menu will give you a standard &kde; Print dialog from where you can print +your diagrams. +</para> +</sect2> +<sect2 id="logical-folders"> +<title>Logical Folders</title> +<para> +To better organize your model, especially for larger projects, you can create logical folders in +the Tree View. Just select the option <menuchoice><guimenu>New</guimenu><guimenuitem>Folder</guimenuitem></menuchoice> from the context menu +of the default folders in the Tree View to create them. Folders can be nested, and you can +move objects around by dragging them from one folder and dropping them into another. +</para> + +<screenshot> +<screeninfo>Organizing your Model with Folders</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="folders.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Organizing a Model with Logical Folders in &umbrello;</phrase> + </textobject> + <caption> + <para>Organizing a Model with Logical Folders in &umbrello; + </para> + </caption> + </mediaobject> +</screenshot> + +</sect2> +</sect1> +</chapter> diff --git a/doc/umbrello/sequence-diagram.png b/doc/umbrello/sequence-diagram.png Binary files differnew file mode 100644 index 00000000..a5f9fbbc --- /dev/null +++ b/doc/umbrello/sequence-diagram.png diff --git a/doc/umbrello/state-diagram.png b/doc/umbrello/state-diagram.png Binary files differnew file mode 100644 index 00000000..610b2133 --- /dev/null +++ b/doc/umbrello/state-diagram.png diff --git a/doc/umbrello/umbrello-main-screen.png b/doc/umbrello/umbrello-main-screen.png Binary files differnew file mode 100644 index 00000000..52c48734 --- /dev/null +++ b/doc/umbrello/umbrello-main-screen.png diff --git a/doc/umbrello/umbrello-ui-clean.png b/doc/umbrello/umbrello-ui-clean.png Binary files differnew file mode 100644 index 00000000..8b147866 --- /dev/null +++ b/doc/umbrello/umbrello-ui-clean.png diff --git a/doc/umbrello/umbrello-ui.png b/doc/umbrello/umbrello-ui.png Binary files differnew file mode 100644 index 00000000..ee3d5911 --- /dev/null +++ b/doc/umbrello/umbrello-ui.png diff --git a/doc/umbrello/uml_basics.docbook b/doc/umbrello/uml_basics.docbook new file mode 100644 index 00000000..e9ad0d0d --- /dev/null +++ b/doc/umbrello/uml_basics.docbook @@ -0,0 +1,616 @@ +<chapter id="uml-basics"> +<title>&UML; Basics</title> +<sect1 id="about-uml"> +<title>About &UML;</title> +<para> +This chapter will give you a quick overview of the basics of &UML;. Keep in mind +that this is not a comprehensive tutorial on &UML; but rather a brief introduction to &UML; which can be read as a &UML; tutorial. +If you would like to learn more about the +Unified Modelling Language, or in general about software analysis and design, refer to one of the +many books available on the topic. There are also a lot of tutorials on the Internet which you +can take as a starting point. +</para> + +<para> +The Unified Modelling Language (&UML;) is a diagramming language or notation to specify, visualize and document +models of Object Orientated software systems. &UML; is not a development method, that means it does not tell you +what to do first and what to do next or how to design your system, but it helps you to visualize +your design and communicate with others. &UML; is controlled by the Object Management Group (<acronym>OMG</acronym>) and is the +industry standard for graphically describing software. +</para> +<para> +&UML; is designed for Object Orientated software design and has limited use for other programming paradigms. +</para> +<para> +&UML; is composed of many model elements that represent the different parts of a software system. +The &UML; elements are used to create diagrams, which represent a certain part, or a point of view of +the system. +The following types of diagrams are supported by &umbrello;: +</para> + +<itemizedlist> + +<listitem><para><emphasis><link linkend="use-case-diagram">Use Case +Diagrams</link></emphasis> show actors (people or other users of the +system), use cases (the scenarios when they use the system), and their +relationships</para> </listitem> + +<listitem><para><emphasis><link linkend="class-diagram">Class +Diagrams</link></emphasis> show classes and the relationships between +them</para> </listitem> + +<listitem><para><emphasis><link linkend="sequence-diagram">Sequence +Diagrams</link></emphasis> show objects and a sequence of method calls +they make to other objects.</para> </listitem> + +<listitem><para><emphasis><link +linkend="collaboration-diagram">Collaboration +Diagrams</link></emphasis> show objects and their relationship, + putting emphasis on the objects that participate in the message exchange</para> +</listitem> + +<listitem><para><emphasis><link linkend="state-diagram">State +Diagrams</link></emphasis> show states, state changes and events in an +object or a part of the system</para> </listitem> + +<listitem><para><emphasis><link linkend="activity-diagram">Activity +Diagrams</link></emphasis> show activities and the changes from one +activity to another with the events occurring in some part of the +system</para></listitem> + +<listitem><para><emphasis><link linkend="component-diagram">Component +Diagrams</link></emphasis> show the high level programming components +(such as KParts or Java Beans).</para></listitem> + +<listitem><para><emphasis><link +linkend="deployment-diagram">Deployment Diagrams</link></emphasis> show +the instances of the components and their +relationships.</para></listitem> + +</itemizedlist> + +</sect1> <!-- about-uml --> + +<sect1 id="uml-elements"> +<title>&UML; Elements</title> +<sect2 id="use-case-diagram"> +<title>Use Case Diagram</title> +<para>Use Case Diagrams describe the relationships and dependencies between a group of <emphasis>Use Cases</emphasis> +and the Actors participating in the process.</para> +<para>It is important to notice that Use Case Diagrams are not suited to represent the design, +and cannot describe the internals of a system. Use Case Diagrams are meant to facilitate the communication +with the future users of the system, and with the customer, and are specially helpful to determine the required +features the system is to have. Use Case Diagrams tell, <emphasis>what</emphasis> the system +should do but do not — and cannot — specify <emphasis>how</emphasis> this is to be achieved.</para> +<para> +<screenshot> +<screeninfo>An example Use Case diagram.</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="use-case-diagram.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&umbrello; showing a Use Case Diagram</phrase> + </textobject> + <caption> + <para>&umbrello; showing a Use Case Diagram + </para> + </caption> + </mediaobject> +</screenshot> +</para> +<sect3 id="use-case"> +<title>Use Case</title> +<para>A <emphasis>Use Case</emphasis> describes — from the point of view of the actors — a group of activities +in a system that produces a concrete, tangible result.</para> +<para> +Use Cases are descriptions of the typical interactions between the users of a system and the system itself. +They represent the external interface of the system and specify a form of requirements of what the +system has to do (remember, only what, not how). +</para> +<para>When working with Use Cases, it is important to remember some simple rules: + <itemizedlist> + <listitem><para>Each Use Case is related to at least one actor</para></listitem> + <listitem><para>Each Use Case has an initiator (&ie; an actor)</para></listitem> + <listitem><para>Each Use Case leads to a relevant result (a result with <quote>business value</quote>)</para> + </listitem> + </itemizedlist> +</para> +<para> +Use Cases can also have relationships with other Use Cases. The three most typical types of relationships +between Use Cases are:</para> +<itemizedlist> +<listitem><para><emphasis><<include>></emphasis> which specifies that a Use Case takes place <emphasis>inside</emphasis> +another Use Case</para></listitem> +<listitem><para><emphasis><<extends>></emphasis> which specifies that in certain situations, or at some point (called an +extension point) a Use Case will be extended by another.</para></listitem> +<listitem><para><emphasis>Generalization</emphasis> specifies that a Use Case inherits the characteristics +of the <quote>Super</quote>-Use Case, and can override some of them or add new ones in a similar way as the +inheritance between classes. +</para> +</listitem> +</itemizedlist> +</sect3> +<sect3 id="actor"> +<title>Actor</title> +<para> +An actor is an external entity (outside of the system) that interacts with the system by participating +(and often initiating) a Use Case. Actors can be in real life people (for example users of the system), +other computer systems or external events. +</para> +<para> +Actors do not represent the <emphasis>physical</emphasis> people or systems, but their <emphasis>role</emphasis>. +This means that when a person interacts with the system in different ways (assuming different roles) he will be +represented by several actors. For example a person that gives customer support by the telephone and takes +orders from the customer into the system would be represented by an actor <quote>Support Staff</quote> and +an actor <quote>Sales Representative</quote> +</para> +</sect3> +<sect3 id="use-case-description"> +<title>Use Case Description</title> +<para> <!-- FIXME this are not defined by UML. --> +Use Case Descriptions are textual narratives of the Use Case. They usually take the form of a note or +a document that is somehow linked to the Use Case, and explains the processes or activities that take +place in the Use Case. +</para> +</sect3> +</sect2> <!-- use-case-diagram --> + +<sect2 id="class-diagram"> +<title>Class Diagram</title> +<para> +Class Diagrams show the different classes that make up a system and how they relate to each other. Class Diagrams +are said to be <quote>static</quote> diagrams because they show the classes, along with their methods and +attributes as well as the static relationships between them: which classes <quote>know</quote> about which classes +or which classes <quote>are part</quote> of another class, but do not show the method calls +between them. +</para> +<para> +<screenshot> +<screeninfo>An example of a Class Diagram</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="class-diagram.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&umbrello; showing a Class Diagram</phrase> + </textobject> + <caption> + <para>&umbrello; showing a Class Diagram + </para> + </caption> + </mediaobject> +</screenshot> +</para> +<sect3 id="class"> +<title>Class</title> +<para> +A Class defines the attributes and the methods of a set of objects. All objects of this class (instances +of this class) share the same behavior, and have the same set of attributes (each object has its own set). +The term <quote>Type</quote> is sometimes used instead of Class, but it is important to mention that these +two are not the same, and Type is a more general term. +</para> +<para> +In &UML;, Classes are represented by rectangles, with the name of the class, and can also show +the attributes and operations of the class in two other <quote>compartments</quote> inside the rectangle. +</para> +<para> +<screenshot> +<screeninfo>A Class in &UML;</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="class.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Visual representation of a Class in &UML;</phrase> + </textobject> + <caption> + <para>Visual representation of a Class in &UML; + </para> + </caption> + </mediaobject> +</screenshot> +</para> +<sect4 id="attribute"> +<title>Attributes</title> +<para> +In &UML;, Attributes are shown with at least their name, and can also show their type, initial value and +other properties. +Attributes can also be displayed with their visibility: +</para> +<itemizedlist> +<listitem><para><literal>+</literal> Stands for <emphasis>public</emphasis> attributes</para></listitem> +<listitem><para><literal>#</literal> Stands for <emphasis>protected</emphasis> attributes</para></listitem> +<listitem><para><literal>-</literal> Stands for <emphasis>private</emphasis> attributes</para></listitem> +</itemizedlist> +</sect4> +<sect4 id="operation"> +<title>Operations</title> +<para> +Operations (methods) are also displayed with at least their name, and can also show their parameters and return +types. +Operations can, just as Attributes, display their visibility: +<itemizedlist> +<listitem><para><literal>+</literal> Stands for <emphasis>public</emphasis> operations</para></listitem> +<listitem><para><literal>#</literal> Stands for <emphasis>protected</emphasis> operations</para></listitem> +<listitem><para><literal>-</literal> Stands for <emphasis>private</emphasis> operations</para></listitem> +</itemizedlist> +</para> +</sect4> + +<sect4 id="templates"> +<title>Templates</title> +<para> +Classes can have templates, a value which is used for an unspecified class or type. The template type is specified +when a class is initiated (&ie; an object is created). Templates exist in modern C++ and will be introduced in Java 1.5 where +they will be called Generics. +</para> +</sect4> +</sect3> + +<sect3 id="class-associations"> +<title>Class Associations</title> +<para>Classes can relate (be associated with) to each other in different ways:</para> +<sect4 id="generalization"> +<title>Generalization</title> +<para>Inheritance is one of the fundamental concepts of Object Orientated programming, in which a class +<quote>gains</quote> all of the attributes and operations of the class it inherits from, and can +override/modify some of them, as well as add more attributes and operations of its own.</para> +<para> +In &UML;, a <emphasis>Generalization</emphasis> association between two classes puts them in a hierarchy +representing the concept of inheritance of a derived class from a base class. In &UML;, Generalizations are +represented by a line connecting the two classes, with an arrow on the side of the base class. +<screenshot> +<screeninfo>Generalization</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="generalization.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Visual representation of a generalization in &UML;</phrase> + </textobject> + <caption> + <para>Visual representation of a generalization in &UML; + </para> + </caption> + </mediaobject> +</screenshot> +</para> +</sect4> + +<sect4 id="uml-associations"> +<title>Associations</title> +<para>An association represents a relationship between classes, and gives the common semantics and structure +for many types of <quote>connections</quote> between objects.</para> +<para>Associations are the mechanism that allows objects to communicate to each other. It describes the connection +between different classes (the connection between the actual objects is called object connection, or +<emphasis>link</emphasis>. +</para> +<para> +Associations can have a role that specifies the purpose of the association and can be uni- or bidirectional +(indicates if the two objects participating in the relationship can send messages to the other, of if only +one of them knows about the other). Each end of the association also has a multiplicity value, which dictates +how many objects on this side of the association can relate to one object on the other side. +</para> +<para> +In &UML;, associations are represented as lines connecting the classes participating in the relationship, +and can also show the role and the multiplicity of each of the participants. Multiplicity is displayed as a +range [min..max] of non-negative values, with a star (<literal>*</literal>) on the maximum side representing infinite. +<screenshot> +<screeninfo>&UML; Association</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="association.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Visual representation of an Association in &UML;</phrase> + </textobject> + <caption> + <para>Visual representation of an Association in &UML; + </para> + </caption> + </mediaobject> +</screenshot> +</para> +</sect4> + +<sect4 id="aggregation"> +<title>Aggregation</title> +<para>Aggregations are a special type of associations in which the two participating classes don't have +an equal status, but make a <quote>whole-part</quote> relationship. An Aggregation describes how the class +that takes the role of the whole, is composed (has) of other classes, which take the role of the parts. +For Aggregations, the class acting as the whole always has a multiplicity of one. +</para> +<para> +In &UML;, Aggregations are represented by an association that shows a rhomb on the side of the whole. +<screenshot> +<screeninfo>Aggregation</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="aggregation.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Visual representation of an Aggregation relationship in &UML;</phrase> + </textobject> + <caption> + <para>Visual representation of an Aggregation relationship in &UML; + </para> + </caption> + </mediaobject> +</screenshot> +</para> +</sect4> +<sect4 id="composition"> +<title>Composition</title> +<para>Compositions are associations that represent <emphasis>very strong</emphasis> aggregations. This means, +Compositions form whole-part relationships as well, but the relationship is so strong that the parts cannot +exist on its own. They exist only inside the whole, and if the whole is destroyed the parts die too.</para> +<para>In &UML;, Compositions are represented by a solid rhomb on the side of the whole. +</para> +<para><screenshot> +<screeninfo>Composition</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="composition.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Visual representation of a Composition relationship in &UML;</phrase> + </textobject> + </mediaobject> +</screenshot></para> +</sect4> +</sect3> <!--class-associations--> + +<sect3 id="other-class-diagram-items"> +<title>Other Class Diagram Items</title> +<para>Class diagrams can contain several other items besides classes.</para> +<sect4 id="interfaces"> +<title>Interfaces</title> +<para>Interfaces are abstract classes which means instances can not be directly created of them. They can contain operations but no attributes. Classes can inherit from interfaces (through a realisation association) and instances can then be made of these diagrams.</para> +<!-- FIXME screenshot --> +</sect4> +<sect4 id="datatype"> +<title>Datatypes</title> +<para>Datatypes are primitives which are typically built into a programming language. Common examples include integers and booleans. +They can not have relationships to classes but classes can have relationships to them.</para> +<!-- FIXME screenshot --> +</sect4> +<sect4 id="enum"> +<title>Enums</title> +<para>Enums are a simple list of values. A typical example is an enum for days of the week. The options of an enum are called Enum Literals. +Like datatypes they can not have relationships to classes but classes can have relationships to them.</para> +<!-- FIXME screenshot --> +</sect4> +<sect4 id="package"> +<title>Packages</title> +<para>Packages represent a namespace in a programming language. In a diagram +they are used to represent parts of a system which contain more than one class, maybe hundereds of classes.</para> +<!-- FIXME screenshot --> +</sect4> +</sect3> + +</sect2> <!-- class diagram --> + +<sect2 id="sequence-diagram"> +<title>Sequence Diagrams</title> + +<para> Sequence Diagrams show the message exchange (&ie; method call) +between several Objects in a specific time-delimited +situation. Objects are instances of classes. +Sequence Diagrams put special emphasis in the order and the +times in which the messages to the objects are sent.</para> + +<para> +In Sequence Diagrams objects are represented through vertical dashed lines, with the name of the Object +on the top. The time axis is also vertical, increasing downwards, so that messages are sent from one Object +to another in the form of arrows with the operation and parameters name. +</para> + +<!-- FIXME update screenshot to show synchronous messages --> +<screenshot> +<screeninfo>Sequence Diagram</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="sequence-diagram.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&umbrello; showing a Sequence Diagram</phrase> + </textobject> + <caption> + <para>&umbrello; showing a Sequence Diagram + </para> + </caption> + </mediaobject> +</screenshot> + +<para>Messages can be either synchronous, the normal type of message call where control is passed to the called object until that +method has finished running, or asynchronous where control is passed back directly to the calling object. Synchronous messages have +a vertical box on the side of the called object to show the flow of program control.</para> +</sect2> <!-- sequence diagrams --> + +<sect2 id="collaboration-diagram"> +<title>Collaboration Diagrams</title> + +<para>Collaboration Diagrams show the interactions occurring between the objects participating in a specific +situation. This is more or less the same information shown by Sequence Diagrams but there the emphasis is +put on how the interactions occur in time while the Collaboration Diagrams +put the relationships between the objects and their topology in the foreground.</para> + +<para>In Collaboration Diagrams messages sent from one object to another are represented by arrows, showing +the message name, parameters, and the sequence of the message. Collaboration Diagrams are specially well suited +to showing a specific program flow or situation and are one of the best diagram types to quickly demonstrate +or explain one process in the program logic. +</para> + +<screenshot> +<screeninfo>Collaboration</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="collaboration-diagram.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&umbrello; showing a Collaboration Diagram</phrase> + </textobject> + <caption> + <para>&umbrello; showing a Collaboration Diagram + </para> + </caption> + </mediaobject> +</screenshot> + +</sect2> <!-- collaboration diagrams --> + +<sect2 id="state-diagram"> +<title>State Diagram</title> +<para>State Diagrams show the different states of an Object during its life and the stimuli that +cause the Object to change its state. +</para> +<para>State Diagrams view Objects as <emphasis>state machines</emphasis> or finite automates that can +be in one of a set of finite states and that can change its state via one of a finite set of stimuli. For example +an Object of type <emphasis>NetServer</emphasis> can be in one of following states during its life: +</para> +<itemizedlist> +<listitem><para>Ready</para></listitem> +<listitem><para>Listening</para></listitem> +<listitem><para>Working</para></listitem> +<listitem><para>Stopped</para></listitem> +</itemizedlist> +<para>and the events that can cause the Object to change states are</para> +<itemizedlist> +<listitem><para>Object is created</para></listitem> +<listitem><para>Object receives message listen</para></listitem> +<listitem><para>A Client requests a connection over the network</para></listitem> +<listitem><para>A Client terminates a request</para></listitem> +<listitem><para>The request is executed and terminated</para></listitem> +<listitem><para>Object receives message stop</para></listitem> +<listitem><para>etc</para></listitem> +</itemizedlist> +<para> +<screenshot> +<screeninfo>State Diagram</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="state-diagram.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&umbrello; showing a State Diagram</phrase> + </textobject> + <caption> + <para>&umbrello; showing a State Diagram + </para> + </caption> + </mediaobject> +</screenshot> +</para> +<sect3 id="state"> +<title>State</title> +<para>States are the building block of State Diagrams. A State belongs to exactly one class and represents +a summary of the values the attributes of a class can take. A &UML; State describes the internal state of an +object of one particular class +</para> +<para>Note that not every change in one of the attributes of an object should be represented by a State +but only those changes that can significantly affect the workings of the object</para> +<para> +There are two special types of States: Start and End. They are special in that there is no event that +can cause an Object to return to its Start state, in the same way as there is no event that can possible take +an Object out of its End state once it has reached it. +</para> +</sect3> + +</sect2> <!-- state diagrams --> + +<sect2 id="activity-diagram"> +<title>Activity Diagram</title> +<para>Activity Diagrams describe the sequence of activities in a system with the +help of Activities. Activity Diagrams are a special form of State Diagrams, that only (or mostly) contains +Activities. +</para> +<para> +<screenshot> +<screeninfo>An example Activity Diagram.</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="activity-diagram.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&umbrello; showing an Activity Diagram</phrase> + </textobject> + <caption> + <para>&umbrello; showing an Activity Diagram + </para> + </caption> + </mediaobject> +</screenshot> +</para> +<para>Activity Diagrams are similar to procedural Flux Diagrams, with the difference that all Activities +are clearly attached to Objects.</para> + +<para>Activity Diagrams are always associated to a +<emphasis>Class</emphasis>, an <emphasis>Operation</emphasis> or a +<emphasis>Use Case</emphasis>.</para> + +<para>Activity Diagrams support sequential as well as parallel Activities. Parallel execution is represented +via Fork/Wait icons, and for the Activities running +in parallel, it is not important the order in which they are carried out (they can be executed at the same +time or one after the other)</para> +<sect3 id="activity"> +<title>Activity</title> +<para>An Activity is a single step in a process. One Activity is one state +in the system with internal activity and, at least, one outgoing transition. Activities can also have +more than one outgoing transition if they have different conditions. +</para> +<para>Activities can form hierarchies, this means that an Activity can be composed of several <quote>detail</quote> +Activities, in which case the incoming and outgoing transitions should match the incoming and outgoing transitions +of the detail diagram. +</para> + +</sect3> +</sect2> <!-- activity diagram --> + +<sect2 id="helper-elements"> +<title>Helper Elements</title> +<para>There are a few elements in &UML; that have no real semantic value for the model, but help to clarify +parts of the diagram. These elements are </para> +<itemizedlist> +<listitem><para>Text lines</para></listitem> +<listitem><para>Text Notes and anchors</para></listitem> +<listitem><para>Boxes</para></listitem> +</itemizedlist> +<para> +Text lines are useful to add short text information to a diagram. It is free-standing text and has no +meaning to the Model itself. +</para> + +<para> +Notes are useful to add more detailed information about an +object or a specific situation. They have the great advantage that +notes can be anchored to &UML; Elements to show that the note +<quote>belongs</quote> to a specific object or situation. +</para> + +<para>Boxes are free-standing rectangles which can be used to group items together to make diagrams more readable. They +have no logical meaning in the model.</para> + +<!-- FIXME, screenshot --> +</sect2> <!-- helper elements --> + +<sect2 id="component-diagram"> +<title>Component Diagrams</title> +<para>Component Diagrams show the software components (either component technologies such as KParts, CORBA components or Java Beans or +just sections of the system which are clearly distinguishable) and the artifacts they +are made out of such as source code files, programming libraries or relational database tables.</para> + +<para>Components can have interfaces (&ie; abstract classes with operations) that allow associations between components.</para> +</sect2> + +<sect2 id="deployment-diagram"> +<title>Deployment Diagrams</title> + +<para>Deployment diagrams show the runtime component instances and their +associations. They include Nodes which are physical resources, +typically a single computer. They also show interfaces and objects (class instances).</para> + +</sect2> + +</sect1> +</chapter> diff --git a/doc/umbrello/use-case-diagram.png b/doc/umbrello/use-case-diagram.png Binary files differnew file mode 100644 index 00000000..36f4320d --- /dev/null +++ b/doc/umbrello/use-case-diagram.png diff --git a/doc/umbrello/working_with_umbrello.docbook b/doc/umbrello/working_with_umbrello.docbook new file mode 100644 index 00000000..3cf32f83 --- /dev/null +++ b/doc/umbrello/working_with_umbrello.docbook @@ -0,0 +1,448 @@ +<chapter id="working-with-umbrello"> +<title>Working with &umbrello;</title> +<!-- Umbrello basics: creating diagrams, creating classes, adding objects to diagrams, + associations, editing properties, anchor points in associations, removing objects, removing + diagrams +--> + +<para> +This chapter will introduce you to &umbrello;'s user interface and will +tell you all you need to know to start modelling. All actions in &umbrello; are accessible via the menu and +the toolbars, but &umbrello; also makes extensive use of &RMB; context menus. You can &RMB; click on almost any element in +&umbrello;'s work area or tree view to get a menu with the most useful +functions that can be applied to the particular element you are +working on. Some users find this a little confusing at the beginning because they are more used to working with the menu or tool bars, but +once you get used to <mousebutton>right</mousebutton> clicking it will greatly speed up your work. +</para> + +<sect1 id="user-interface"> +<title>User Interface</title> +<para> +&umbrello;'s main window is divided in three areas that will help you keep an overview of your entire system +and access the different diagrams quickly while working on your model. +</para> +<para>These areas are called:</para> +<itemizedlist> +<listitem><para>Tree View</para></listitem> +<listitem><para>Work Area</para></listitem> +<listitem><para>Documentation Window</para></listitem> +</itemizedlist> + +<screenshot> +<screeninfo>&umbrello;'s User Interface</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="umbrello-ui.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&umbrello;'s User Interface</phrase> + </textobject> + <caption> + <para>&umbrello;'s User Interface + </para> + </caption> + </mediaobject> +</screenshot> + +<sect2 id="tree-view"> +<title>Tree View</title> +<para> +The Tree View is usually located on the top left hand side of the window and shows the all the diagrams, +classes, actors and use cases that build up your model. +The Tree View allows you to have a quick overview of the elements composing your model. The Tree View also +gives you a quick way to switch between the different diagrams in your model and inserting elements from +your model into the current diagram. +</para> +<para> +If you are working on a model with more than just a few classes and diagrams, the Tree View may help +you stay on top of things by organizing your model elements in folders. You can create +folders by selecting the appropriate option from the context menu (&RMB; click on one of the folders +in the tree view) and you can organize your elements by moving them to the appropriate folder (drag and drop) +<!-- (screen shot) FIXME--> +</para> +</sect2> + +<sect2 id="documentation-window"> +<title>Documentation Window</title> +<para> +The Documentation Window is the small window located on the left bottom of &umbrello;, and it gives +you a quick preview of the documentation for the currently selected item. The Documentation Window is +rather small because it is intended to allow you just a quick pick into the element's documentation while +taking as little screen space as possible. If you need to view the documentation in more detail you can always +open the item's properties. +</para> +</sect2> +<sect2 id="work-area"> +<title>Work Area</title> +<para> +The Work Area is the main window in &umbrello; and is where the real action takes place. You use the Work Area +to edit and view the diagrams in your model. The Work Area shows the currently active diagram. Currently +only one diagram can be shown on the Work Area at any time. +</para> +</sect2> +</sect1> <!--user-interface--> +<sect1 id="load-save"> +<title>Creating, Loading and Saving Models</title> +<para> +The first thing you need to start doing something useful with &umbrello; is to create a model to work on. +When you start &umbrello; it always loads the last used model or creates a new, empty model (depending on +your preferences set in the configuration dialog). This will allow you to start working right away. +</para> +<sect2 id="new-model"> +<title>New Model</title> +<para> +If at any time you need to create a new model you can do this by selecting the <guimenuitem>New</guimenuitem> entry from the +<guimenu>File</guimenu> menu, or by clicking on the <guiicon>New</guiicon> icon from the application toolbar. If you are currently working on +a model which has been modified &umbrello; will ask you if it should save your changes before loading the +new model. +</para> +</sect2> +<sect2 id="save-model"> +<title>Save Model</title> +<para> +You can save your model at any time by selecting the option <guimenuitem>Save</guimenuitem> from the <guimenu>File</guimenu> Menu or by clicking +on the <guiicon>Save</guiicon> button from the application toolbar. If you need to save your model under a different name +you can use the option <guimenuitem>Save As</guimenuitem> from the <guimenu>File</guimenu> Menu. +</para> +<para>For your convenience &umbrello; also offers you the option to automatically save your work +each certain time period. You can configure if you want this option as well as the time intervals +in the <guimenu>Settings</guimenu> from &umbrello;</para> +</sect2> +<sect2 id="load-model"> +<title>Load Model</title> +<para> +For loading an already existing model you may select the option <guimenuitem>Open</guimenuitem> from the <guimenu>File</guimenu> Menu or click on the <guiicon>Open</guiicon> +icon from the application toolbar. The most recently used models are also available under the submenu +<guimenuitem>Open Recent</guimenuitem> in the <guimenu>File</guimenu> Menu to speed up access to your most frequently used models. +</para> +<para> +&umbrello; can only work on one model at a time, so if you ask the program to load a model for you and your +current model has been modified since the last time you save it, &umbrello; will ask you whether your changes +should be saved to prevent any loss of work. You can start two or more instances of &umbrello; at any one time, you can also copy and paste between instances. +</para> +</sect2> +</sect1> <!--load-save--> +<sect1 id="edit-model"> +<title>Editing Models</title> +<para> +In &umbrello;, there are basically two ways for editing the elements in your model. +<itemizedlist> +<listitem><para>Edit model elements directly through the Tree View</para></listitem> +<listitem><para>Edit model elements through a Diagram</para></listitem> +</itemizedlist> +</para> +<para> +Using the context menu of the different items in the Tree View you are able to add, remove, +and modify almost all the elements in your model. <mousebutton>Right</mousebutton> clicking on the folders in the Tree View +will give you options for creating the different types of diagrams as well as, depending on whether +the folder is a <emphasis>Use Case View</emphasis> or a <emphasis>Logical View</emphasis>, Actors, +Use Cases, Classes, etc. +</para> +<para> +Once you have added elements to your model you can also edit an element by accessing its properties +dialog, which you find by selecting the option <emphasis>Properties</emphasis> from the context menu +shown when <mousebutton>right</mousebutton> clicking on the items in the Tree View. +</para> +<para> +You can also edit your model by creating or modifying elements through diagrams. More details on how +to do this are given in the following sections. +</para> +</sect1> +<sect1 id="add-remove-diagrams"> +<title>Adding and Removing Diagrams</title> +<para> +Your &UML; model consists of a set of &UML; elements and associations between them. However you cannot see the model +directly, you use <emphasis>Diagrams</emphasis> to look at it. +</para> +<sect2 id="create-diagram"> +<title>Creating Diagrams</title> +<para> +To create a new diagram in your model simply select the diagram type you need from the <guimenuitem>New</guimenuitem> submenu in the <guimenu>Diagram</guimenu> menu and give a name to it. The diagram will be created and made active, and you will immediately +see it in the tree view. +</para> +<para> +Remember that &umbrello; makes extensive use of context menus: you can also &RMB; click on a folder in the Tree +View and select the appropriate diagram type from the <guisubmenu>New</guisubmenu> submenu in the context menu. Note that you can create +Use Case Diagrams only in Use Case View folders, and the other types of diagram can only be created in the +Logical View folders. +</para> +</sect2> +<sect2 id="remove-diagram"> +<title>Removing Diagrams</title> +<para> +Should you need to remove a diagram from your model, you can do this by making it active and selecting +<guimenuitem>Delete</guimenuitem> from the <guimenu>Diagram</guimenu> Menu. You can also achieve this by selecting <guimenuitem>Delete</guimenuitem> from the diagrams context menu +in the Tree View +</para> +<para>Since deleting a diagram is something serious that could cause loss of work if done by accident, &umbrello; +will ask you to confirm the delete operation before actually removing the Diagram. Once a diagram has been +deleted and the file has been saved there is no way to undo this action. +</para> +</sect2> +<sect2 id="rename-diagram"> +<title>Renaming Diagrams</title> +<para> +If you want to change the name of an existing diagram you can easily do this by selecting the Rename option +from its &RMB; menu in the Tree View. +</para> +<para>Another way to rename a diagram is to do this via its properties dialog, which you obtain by +selecting Properties from its Context Menu or by double clicking on it in the Tree View. +</para> +</sect2> +</sect1> +<sect1 id="edit-diagram"> +<title>Editing Diagrams</title> +<para> +When working on a diagram, &umbrello; will try to guide you by applying some simple rules as to which +elements are valid in the different types of diagrams, as well as the relationships that can exist +between them. If you are an &UML; expert you will probably not even notice it, but this will help +&UML; novices create standard-conformant diagrams. +</para> +<para> +Once you have created your diagrams it is time to start editing them. Here you should notice +the (for beginners subtle) difference between editing your diagram, and editing the +<emphasis>model</emphasis>. As you already know, Diagrams are <emphasis>views</emphasis> of your model. +For example, if you create a class by editing a Class Diagram, you are really editing both, your +Diagram and your model. If you change the color or other display options of a Class in your Class +Diagram, you are only editing the Diagram, but nothing is changed in your model. +</para> +<sect2 id="insert-elements"> +<title>Insert Elements</title> +<para> +One of the first things you will do when editing a new diagram is to insert elements into them (Classes, +Actors, Use Cases, &etc;) There is basically two ways of doing this:</para> +<itemizedlist> +<listitem><para>Dragging existing elements in your model from the Tree View</para></listitem> +<listitem><para>Creating new elements in your model and adding them to your diagram at the +same time, by using one of the edit Tools in the Work Toolbar</para></listitem> +</itemizedlist> +<para> +To insert elements that already exist in your model, just drag them from the Tree View and +drop them where you want them to be in your diagram. You can always move elements around +in your Diagram using the Select Tool +</para> +<para> +The second way of adding elements to your diagram is by using the Work Toolbar's edit tools (note +that this will also add the elements to your model). +</para> +<para> +The Work Toolbar was by default located on the far right of the application window, &umbrello; 1.2 has moved this to the top of the window. +You can dock it into other edge or have it floating around if you prefer. The tools available +on this toolbar (the buttons you see on it) change depending on the type of diagram +you are currently working on. The button for the currently +selected tool is activated in the toolbar. You can switch to the select tool +by pressing the &Esc; key. +</para> +<para> +When you have selected an edit tool from the Work Toolbar (for example, the tool to insert classes) +the mouse pointer changes to a cross, and you can insert the elements in your model by single clicking +in your diagram. Note that elements in &UML; must have a <emphasis>Unique Name</emphasis>. So that if +you have a class in one diagram whose name is <quote>ClassA</quote> and then you use the insert Class +tool to insert a class into another diagram you cannot name this new class <quote>ClassA</quote> as well. +If these two are supposed to be two different elements, you have to give them a unique name. If you are +trying to add the <emphasis>same</emphasis> element to your diagram, then the Insert Class is not +the right tool for that. You should drag and drop the class from the Tree View instead. +</para> +</sect2> +<sect2 id="delete-elements"> +<title>Deleting Elements</title> +<para> +You can delete any element by selecting the option <guimenuitem>Delete</guimenuitem> from its context menu. +</para> +<para> +Again, there is a <emphasis>big</emphasis> difference between removing an object from a diagram, and +deleting an object from your model: +If you delete an object from within a diagram, you are only removing the object from that particular +diagram: the element will still be part of your model and if there are other diagrams using the same +element they will not suffer any change. +If, on the other hand, you delete the element from the Tree View, you are actually deleting the +element from your <emphasis>model</emphasis>. Since the element no longer exist in your model, +it will be automatically removed from all the diagrams it appears in. +</para> +</sect2> +<sect2 id="edit-elements"> +<title>Editing Elements</title> +<para> +You can edit most of the &UML; elements in your model and diagrams by opening its Properties dialog +and selecting the appropriate options. +To edit the properties of an object, select <guimenuitem>Properties</guimenuitem> from its context menu (&RMB; click). Each element has a dialog consisting of several pages where you can configure the options +corresponding to that element. For some elements, like actors you can only set a couple of options, +like the object name and documentation, while for other elements, like classes, you can edit its +attributes and operations, select what you want to be shown in the diagram (whole operation signature +or just operation names, etc) and even the colors you want to use for the line and fill of the class' +representation on the diagram. +</para> + +<para> +For most &UML; elements you can also open the properties dialog by +double clicking on it if you are using the selection tool (arrow). The +exception to this is Associations, in which case a double click +creates an anchor point. For associations you need to use the &RMB; context menu to get the properties dialog. +</para> + +<para> +Note that you can also select the properties option from the context +menu of the elements in the Tree View. This allows you to also edit +the properties for the diagrams, like setting whether the grid should +be shown or not. +</para> +</sect2> +<sect2 id="edit-classes"> +<title>Editing Classes</title> +<para> +Even though editing the properties of all objects was already covered in the previous section, +classes deserve a special section because they are a bit more complicated and have more options +than most of the other &UML; elements. +</para> +<para> +In the properties dialog for a class you can set everything, from the color it uses to the operations +and attributes it has. +</para> +<sect3 id="class-general-settings"> +<title>Class General Settings</title> +<para> +The General Settings page of the properties dialog is self-explanatory. Here you can change the +class' name, visibility, documentation, &etc; +This page is always available. +</para> +</sect3> +<sect3 id="class-attributes-settings"> +<title>Class Attribute Settings</title> +<para> +In the Attributes Settings page you can add, edit, or delete attributes (variables) of the class. +You can move attributes up and down the list by pressing the arrow button +on the side. +This page is always available. +</para> +</sect3> +<sect3 id="class-operations-settings"> +<title>Class Operations Settings</title> +<para> +Similar to the Attribute Settings Page, in the Operation Settings Page you can add, edit, or +remove operations for your class. When adding or editing an operation, you enter the basic data in +the <emphasis>Operation Properties</emphasis> dialog. If you want to add parameters to your operation +you need to click the <guibutton>New Parameter</guibutton> button, which will show the +<emphasis>Parameter Properties</emphasis> dialog. +This page is always available +</para> +</sect3> +<sect3 id="class-template-settings"> +<title>Class Template Settings</title> +<para> +This page allows you to add class templates which are unspecified classes or datatypes. In Java 1.5 these will be called Generics. +</para> +</sect3> +<sect3 id="class-associations-page"> +<title>Class Associations Page</title> +<para> +The <guilabel>Class Associations</guilabel> page shows all the associations of this class +in the current diagram. Double clicking on an association shows its properties, and depending +on the type of association you may modify some parameters here such as setting multiplicity and Role +name. If the association does not allow such options be be modified, the Association Properties dialog +is read-only and you can only modify the documentation associated with this association. +</para> +<para> +This page is only available if you open the Class Properties from within a diagram. If you select +the class properties from the context menu in the Tree View this page is not available. +</para> +</sect3> +<sect3 id="class-display-page"> +<title>Class Display Page</title> +<para> +In the <guilabel>Display Options</guilabel> page, you can set what is to be shown in the diagram. +A class can be shown as only one rectangle with the class name in it (useful if you have many +classes in your diagram, or are for the moment not interested in the details of each class) or +as complete as showing packages, stereotypes, and attributes and operations with full signature and +visibility +</para> +<para>Depending on the amount of information you want to see you can select the corresponding +options in this page. The changes you make here are only <emphasis>display options</emphasis> +for the diagram. This means that <quote>hiding</quote> a class' operations only makes them +not to be shown in the diagram, but the operation are still there as part of your model. +This option is only available if you select the class properties from within a Diagram. If you open +the class properties from the Tree View this page is missing since such Display Options do not make sense +in that case</para> +</sect3> +<sect3 id="class-color-page"> +<title>Class Color Page</title> +<para> +In the <guilabel>Widget Color</guilabel> page you can configure the colors you want for the line +and the fill of the widget. This option obviously makes sense only for classes displayed in diagrams, +and is missing if you open the class' properties dialog from the Tree View. +</para> +</sect3> +</sect2> + +<sect2 id="associations"> +<title>Associations</title> +<para> +Associations relate two &UML; objects to each other. Normally associations are defined between two classes, +but some types of associations can also exists between use cases and actors. +</para> +<para> +To create an association select the appropriate tool from the Work Toolbar (generic Association, +Generalization, Aggregation, &etc;) and single click on the first element participating in the association +and then single click on the second item participating. Note that those are two clicks, one on each +on the objects participating in the association, it is <emphasis>not</emphasis> a drag from one object +to the other. <!-- yet :) --> +</para> +<para> +If you try to use an association in a way against the &UML; specification &umbrello; will refuse to create +the association and you will get an error message. This would be the case if, for example, a Generalization +exists from class A to class B and then you try to create another Generalization from Class B to class A +</para> +<para> +<mousebutton>Right</mousebutton> clicking on an association will show a context menu with the actions you can apply on it. If you need to delete an association simply select the <guimenuitem>Delete</guimenuitem> option from this context menu. +You can also select the <guimenuitem>Properties</guimenuitem> option and, depending on the association type +edit attributes such as roles and multiplicity. +</para> +<sect3 id="anchor-points"> +<title>Anchor Points</title> +<para> +Associations are drawn, by default, as a straight line connecting the two objects in the diagram. +</para> +<para> +You can add anchor points to bend an association by <mousebutton>double</mousebutton> clicking some where along the association line. This will insert +an anchor point (displayed as a blue point when the association line is selected) which you can move +around to give shape to the association +</para> +<para> +If you need to remove an anchor point, <mousebutton>double</mousebutton> click on it again to remove it +</para> +<para> +Note that the only way to edit the properties of an association is through the context menu. If you +try to <mousebutton>double</mousebutton> click on it as with other &UML; objects, this will only insert an anchor point. +</para> +</sect3> +</sect2> + +<sect2 id="notes"> +<title>Notes, Text and Boxes</title> +<para> +Notes, Lines Of Text and Boxes are elements that can be present in any type of diagram and have no real +semantic value, but are very helpful to add extra comments or explanations that can make your +diagram easier to understand. +</para> +<para> +To add a Note or a Line Of Text, select the corresponding tool from the Work Toolbar and single click +on the diagram where you want to put your comment. You can edit the text by opening the element through +its context menu or in the case of notes by <mousebutton>double</mousebutton> clicking on them as well. +</para> +<sect3 id="anchors"> +<title>Anchors</title> +<para> +Anchors are used to link a text note and another &UML; Element together. For example, you normally +use a text note to explain or make some comment about a class or a particular association, in which +case you can use the anchor to make it clear that the note <quote>belongs</quote> to that particular +element. +</para> +<para> +To add an anchor between a note and another &UML; element, use the anchor tool from the work toolbar. +You first need to click on the note and then click on the &UML; element you want the note to be linked +to. +</para> +</sect3> +</sect2> +</sect1> +</chapter> +<!--edit-diagram--> |
