diff options
| author | Darrell Anderson <darrella@hushmail.com> | 2014-01-21 22:06:48 -0600 |
|---|---|---|
| committer | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2014-01-21 22:06:48 -0600 |
| commit | 0b8ca6637be94f7814cafa7d01ad4699672ff336 (patch) | |
| tree | d2b55b28893be8b047b4e60514f4a7f0713e0d70 /tde-i18n-en_GB/docs/tdesdk | |
| parent | a1670b07bc16b0decb3e85ee17ae64109cb182c1 (diff) | |
| download | tde-i18n-0b8ca6637be94f7814cafa7d01ad4699672ff336.tar.gz tde-i18n-0b8ca6637be94f7814cafa7d01ad4699672ff336.zip | |
Beautify docbook files
Diffstat (limited to 'tde-i18n-en_GB/docs/tdesdk')
21 files changed, 2128 insertions, 9354 deletions
diff --git a/tde-i18n-en_GB/docs/tdesdk/cervisia/index.docbook b/tde-i18n-en_GB/docs/tdesdk/cervisia/index.docbook index a769181ee18..890547a5b9f 100644 --- a/tde-i18n-en_GB/docs/tdesdk/cervisia/index.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/cervisia/index.docbook @@ -2,418 +2,190 @@ <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ <!ENTITY kappname "&cervisia;"> <!ENTITY package "tdesdk"> - <!ENTITY ssh "<command ->ssh</command ->"> - <!ENTITY rsh "<command ->rsh</command ->"> + <!ENTITY ssh "<command>ssh</command>"> + <!ENTITY rsh "<command>rsh</command>"> <!ENTITY % addindex "IGNORE"> - <!ENTITY % British-English "INCLUDE" -> <!-- Change language only here --> - <!ENTITY CVS "<application ->CVS</application ->"> + <!ENTITY % British-English "INCLUDE"> <!-- Change language only here --> + <!ENTITY CVS "<application>CVS</application>"> ]> <book lang="&language;"> <bookinfo> -<title ->&cervisia; Manual</title> +<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 -> - - -<othercredit role="translator" -><firstname ->Alex</firstname -><surname ->Walker</surname -><affiliation -><address -><email ->alex@x3ja.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<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> + + +<othercredit role="translator"><firstname>Alex</firstname><surname>Walker</surname><affiliation><address><email>alex@x3ja.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </authorgroup> <copyright> -<year ->1999</year> -<year ->2000</year> -<year ->2001</year> -<year ->2002</year> -<holder ->Bernd Gehrmann</holder> +<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> +<year>2004</year> +<holder>Carlos Woelz</holder> </copyright> <legalnotice> -<para ->This program may be distributed under the terms of the Q Public License as defined by Trolltech AS of Norway and appearing in the file LICENSE.QPL included in the packaging of this file.</para> +<para>This program may be distributed under the terms of the Q Public License as defined by Trolltech AS of Norway and appearing in the file LICENSE.QPL included in the packaging of this file.</para> -<para ->This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</para> +<para>This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</para> </legalnotice> -<legalnotice ->&FDLNotice;</legalnotice> +<legalnotice>&FDLNotice;</legalnotice> -<date ->2004-06-06</date> -<releaseinfo ->2.01.90</releaseinfo> +<date>2004-06-06</date> +<releaseinfo>2.01.90</releaseinfo> <abstract> -<para ->&cervisia; provides a graphical view of &CVS;.</para> +<para>&cervisia; provides a graphical view of &CVS;.</para> </abstract> <keywordset> -<keyword ->KDE</keyword> -<keyword ->tdesdk</keyword> -<keyword ->Cervisia</keyword> -<keyword ->CVS</keyword> -<keyword ->version control</keyword> -<keyword ->revision control</keyword> +<keyword>KDE</keyword> +<keyword>tdesdk</keyword> +<keyword>Cervisia</keyword> +<keyword>CVS</keyword> +<keyword>version control</keyword> +<keyword>revision control</keyword> </keywordset> </bookinfo> <chapter id="introduction"> -<title ->Introduction</title> +<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 tdesdk module or installing the tdesdk package provided by your distribution. Currently, only &CVS; is supported, but other version control systems may be integrated in the future. </para> +<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 tdesdk module or installing the tdesdk 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>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 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> +<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> +<title>Getting Started</title> <sect1 id="accessing-repository"> -<title ->Accessing The Repository</title> +<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> +<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> +<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 -> dialogue 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 edit 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 edit 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 initialise 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> +<title>Creating a Local Repository</title> + +<step><para>Open the <guilabel>Create New Repository (cvs init)</guilabel> dialogue 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 edit 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 edit 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 initialise 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 -> dialogue. To display it, select the <menuchoice -><guimenu ->Repository</guimenu -> <guimenuitem ->Repositories...</guimenuitem -></menuchoice -> menu item. </para> +<para>&cervisia; offers an integrated front-end to manage all your repository locations, the <guilabel>Configure Access to Repositories</guilabel> dialogue. 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 dialogue</title> +<title>A screenshot of &cervisia;'s Configure Access to Repositories dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="repositories.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s Configure Access to Repositories dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="repositories.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s Configure Access to Repositories dialogue</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>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> +<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 categorised as follows: </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 categorised as follows: </para> <variablelist> <varlistentry> -<term ->Local</term> +<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> +<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> +<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> +<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> +<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> +<term>pserver</term> <listitem> -<para ->The repository location looks like <filename ->:pserver:username@host.url.org:/path/to/repository</filename -> </para> +<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>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> +<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> +<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 -> dialogue 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 -> dialogue. </para -></step> - -<step -><para ->Enter the repository location in the <guilabel ->Repository:</guilabel -> edit box. &cervisia; will automatically disable the areas of the dialogue 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</guilabel -> edit 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 pop-up dialogue. </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> +<title>Adding a New Repository</title> + +<step><para>Open the <guilabel>Configure Access to Repositories</guilabel> dialogue 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> dialogue. </para></step> + +<step><para>Enter the repository location in the <guilabel>Repository:</guilabel> edit box. &cervisia; will automatically disable the areas of the dialogue 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</guilabel> edit 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 pop-up dialogue. </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> @@ -421,376 +193,150 @@ <sect1 id="importing"> -<title ->Importing a Module Into the Repository</title> +<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>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> +<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 dialogue. Modules are the top folders in the &CVS; repository folder tree, and are used to separate and organise the different software projects inside the repository. </para -></listitem> +<listitem><para>Import the files and folders to a new <firstterm>module</firstterm>, using &cervisia;'s import dialogue. Modules are the top folders in the &CVS; repository folder tree, and are used to separate and organise 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> +<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> +<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 dialogue 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>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 dialogue 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 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>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 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 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> +<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 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 dialogue</title> +<title>A screenshot of &cervisia;'s import dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="import.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s import dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="import.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s import dialogue</phrase></textobject> </mediaobject> </figure> -<para ->In <xref linkend="screenshot-import"/> you can see the dialogue which helps you to <emphasis ->import</emphasis -> a project as a module. To access &cervisia;'s import dialogue, choose the <menuchoice -><guimenu ->Repository</guimenu -> <guimenuitem ->Import...</guimenuitem -></menuchoice -> menu item. </para> +<para>In <xref linkend="screenshot-import"/> you can see the dialogue which helps you to <emphasis>import</emphasis> a project as a module. To access &cervisia;'s import dialogue, 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 initialised. 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 -> dialogue box. If the repository is remote, make sure that authentication works. See <xref linkend="accessing-repository"/> for more information. </para -></listitem> +<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 initialised. 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> dialogue 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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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>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>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> +<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 dialogue</title> +<title>A screenshot of &cervisia;'s checkout dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="checkout.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s checkout dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="checkout.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s checkout dialogue</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 -> dialogue box. If the repository is remote, make sure that authentication works. See <xref linkend="accessing-repository"/> for more information. </para -></listitem> +<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> dialogue 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 tdesdk module, enter <filename class="directory" ->tdesdk/doc/cervisia</filename -> in this field. </para -></listitem> +<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 tdesdk module, enter <filename class="directory">tdesdk/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> +<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> +<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> +<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> +<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> @@ -799,242 +345,96 @@ <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> +<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> +<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> +<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 <guimenuitem ->Status</guimenuitem -> from the <guimenu ->File</guimenu -> menu, press <keycap ->F5</keycap -> or right click the marked files and choose the <menuchoice -> <guisubmenu ->Status</guisubmenu -> </menuchoice -> menu item from the pop-up menu. &cervisia; issues a</para> +<para>The commands in the File menu usually act only on the files which you have marked. You may also mark folders. Now choose <guimenuitem>Status</guimenuitem> from the <guimenu>File</guimenu> menu, press <keycap>F5</keycap> or right click the marked files and choose the <menuchoice> <guisubmenu>Status</guisubmenu> </menuchoice> menu item from the pop-up menu. &cervisia; issues a</para> <para> -<screen -><command ->cvs update -n <replaceable ->file names</replaceable -></command -></screen> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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 <guimenuitem ->Update</guimenuitem -> from the <guimenu ->File</guimenu -> menu, or right-click the marked files and choose the <menuchoice -> <guisubmenu ->Status</guisubmenu -></menuchoice -> menu item from the pop-up menu. (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> +<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 <guimenuitem>Update</guimenuitem> from the <guimenu>File</guimenu> menu, or right-click the marked files and choose the <menuchoice> <guisubmenu>Status</guisubmenu></menuchoice> menu item from the pop-up menu. (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> +<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> +<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 colour. The colours 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> +<para>You may have noticed that according to the status of the file, its row has a different colour. The colours 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> @@ -1042,404 +442,156 @@ <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> +<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 pop-up menu</title> +<title>A screenshot of &cervisia;'s pop-up menu</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="popup.png"/></imageobject> +<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 pop-up menu. <xref linkend="screenshot-popup"/> shows &cervisia;'s main window pop-up menu. </para> +<para>The most used actions are also available by right-clicking the files in the tree view, through the pop-up 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 <keycap ->Return</keycap ->. 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> +<para>You can simply edit a file by double-clicking on it or selecting it and pressing <keycap>Return</keycap>. 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 -> dialogue will appear, listing the files you marked, and asks for confirmation. Press <guibutton ->OK</guibutton ->. </para> - -<para ->&cervisia; issues a command</para> +<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> dialogue 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> +<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 behaviour 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 -> dialogue will appear, listing the binary files you marked, and asks for confirmation. Press <guibutton ->OK</guibutton ->. </para> - -<para ->&cervisia; issues a command </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 behaviour 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> dialogue 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> +<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 pop-up menu. The <guilabel ->CVS Remove</guilabel -> dialogue will appear, listing the files you marked, and asking for confirmation. Press <guibutton ->OK</guibutton ->. &cervisia; issues the command </para> +<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 pop-up menu. The <guilabel>CVS Remove</guilabel> dialogue 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> +<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> +<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 behaviour 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> +<note><para>The above command only works if the file is up-to-date. Otherwise, you get an error message. This behaviour 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 (expect 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 pop-up menu. Note that in contrast to adding files, adding folders does not require a commit afterwards. &cervisia; issues the command </para> +<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 (expect 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 pop-up 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> +<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 pop-up menu. </para> +<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 pop-up menu. </para> <figure id="screenshot-commit" float="1"> -<title ->A screenshot of &cervisia;'s commit dialogue</title> +<title>A screenshot of &cervisia;'s commit dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="commit.png"/></imageobject> +<imageobject><imagedata format="PNG" fileref="commit.png"/></imageobject> </mediaobject> </figure> -<para ->You get a dialogue 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 dialogue is integrated with &cervisia;'s changelog editor described below. When you have finished the dialogue, the command </para> +<para>You get a dialogue 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 dialogue is integrated with &cervisia;'s changelog editor described below. When you have finished the dialogue, the command </para> <para> -<screen -><command ->cvs commit -m <replaceable ->message</replaceable -> <replaceable ->file names</replaceable -></command -></screen> +<screen><command>cvs commit -m <replaceable>message</replaceable> <replaceable>file names</replaceable></command></screen> </para> -<para ->is used. </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>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>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> +<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> +<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 dialogue this dialogue by clicking <guibutton ->OK</guibutton ->, the next commit dialogue you open will have the log message set to the message you last entered in the ChangeLog. </para> +<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 dialogue this dialogue by clicking <guibutton>OK</guibutton>, the next commit dialogue 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> +<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>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 colour. 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 favourite editor.</para> +<para>In &cervisia;'s main view, files with conflicts are indicated with "Conflict" in the status column and with a red colour. 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 favourite editor.</para> -<para ->&CVS; marks the conflicting changes by placing marks in the middle of the files, in the following manner:</para> +<para>&CVS; marks the conflicting changes by placing marks in the middle of the files, in the following manner:</para> -<screen -><<<<<<< +<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: you can for each conflict decide to take one of the two alternative versions. You can also decide that both approaches are 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 -> dialogue choose <menuchoice -><guimenu ->File</guimenu -><guimenuitem ->Resolve...</guimenuitem -></menuchoice -> or right click the marked file and choose <guimenuitem ->Resolve...</guimenuitem -> from the pop-up menu. </para> +<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: you can for each conflict decide to take one of the two alternative versions. You can also decide that both approaches are 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> dialogue choose <menuchoice><guimenu>File</guimenu><guimenuitem>Resolve...</guimenuitem></menuchoice> or right click the marked file and choose <guimenuitem>Resolve...</guimenuitem> from the pop-up menu. </para> <figure id="screenshot-resolve" float="1"> -<title ->A screenshot of &cervisia;'s resolve dialogue</title> +<title>A screenshot of &cervisia;'s resolve dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="resolve.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s resolve dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="resolve.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s resolve dialogue</phrase></textobject> </mediaobject> </figure> -<para ->On the top of the dialogue, 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 colour. 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 dialogue 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 -> dialogue 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 dialogue. If you close the dialogue without saving, the changes you made will be lost. </para> +<para>On the top of the dialogue, 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 colour. 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 dialogue 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> dialogue 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 dialogue. If you close the dialogue without saving, the changes you made will be lost. </para> </sect1> @@ -1447,638 +599,245 @@ Changes in the repository <chapter id="obtaininginformation"> -<title ->Obtaining Information About Files and Creating Patches</title> +<title>Obtaining Information About Files and Creating Patches</title> <sect1 id="diff"> -<title ->Watching Differences Between Revisions</title> +<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> +<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 pop-up menu, by right-clicking the file you want to view. </para -></listitem> - -<listitem -><para ->In the dialogue 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 dialogue, you can mark two revisions of a file and request a dialogue showing the differences between them (see <xref linkend="browsinglogs"/>). </para -></listitem> +<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 pop-up menu, by right-clicking the file you want to view. </para></listitem> + +<listitem><para>In the dialogue 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 dialogue, you can mark two revisions of a file and request a dialogue 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> +<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 dialogue</title> +<title>A screenshot of &cervisia;'s diff dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="diff.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s diff dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="diff.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s diff dialogue</phrase></textobject> </mediaobject> </figure> -<para ->The text in the dialogue 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 colour. In the middle of the dialogue a compressed image of the colour 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 coloured 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 synchronised, 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 ->Synchronise scroll bars</guibutton ->. </para> - -<para ->For information about how to customise the diff dialogue, see <xref linkend="customize-diff"/>. </para> +<para>The text in the dialogue 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 colour. In the middle of the dialogue a compressed image of the colour 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 coloured 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 synchronised, 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>Synchronise scroll bars</guibutton>. </para> + +<para>For information about how to customise the diff dialogue, 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 to 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 pop-up menu, in order to open the <link linkend="browsinglogs" ->Browse log dialogue</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 dialogue allowing you to configure the output format. </para> +<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 to 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 pop-up menu, in order to open the <link linkend="browsinglogs">Browse log dialogue</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 dialogue allowing you to configure the output format. </para> <figure id="screenshot-patch" float="1"> -<title ->A screenshot of &cervisia;'s patch dialogue</title> +<title>A screenshot of &cervisia;'s patch dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="patch.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s patch dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="patch.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s patch dialogue</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> +<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> +<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> +<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 -> dialogue. Enter in this dialogue the file name and location of the patch file. </para> +<para>After setting the output format, &cervisia; generates the patch and displays the <guilabel>Save As</guilabel> dialogue. Enter in this dialogue 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 to 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 dialogue</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 dialogue. </para> +<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 to 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 dialogue</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 dialogue. </para> <figure id="screenshot-annotate" float="1"> -<title ->A screenshot of &cervisia;'s annotate dialogue</title> +<title>A screenshot of &cervisia;'s annotate dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="annotate.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s annotate dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="annotate.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s annotate dialogue</phrase></textobject> </mediaobject> </figure> -<para ->In the annotate dialogue, you see in a window the latest version of the selected file (or the revision "A" version, in case you launched the annotate dialogue from the the <link linkend="browsinglogs" ->Browse log dialogue</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>In the annotate dialogue, you see in a window the latest version of the selected file (or the revision "A" version, in case you launched the annotate dialogue from the the <link linkend="browsinglogs">Browse log dialogue</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> +<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 pop-up menu, the <guilabel ->CVS Log</guilabel -> dialogue 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 dialogue offers functionality that is beyond viewing the file's history. Using it as a version browser you can: </para> +<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 pop-up menu, the <guilabel>CVS Log</guilabel> dialogue 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 dialogue 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 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 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>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>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>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> +<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 dialogue</title> +<title>A screenshot of &cervisia;'s browse logs dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="logtree.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s browse logs dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="logtree.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s browse logs dialogue</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 dialogue 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 dialogue 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 dialogue 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 colours 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 dialogue 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 dialogue, and pressing <guibutton ->OK</guibutton ->, a <command ->cvs diff</command -> command is issued to generate the difference file. A <guilabel ->Save As</guilabel -> dialogue 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 dialogue and return to the main view. </para> - - -<para ->To generate the log that is the base for the <guilabel ->CVS Log</guilabel -> dialogue, &cervisia; issues the following command: </para> +<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 dialogue 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 dialogue 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 dialogue 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 colours 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 dialogue 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 dialogue, and pressing <guibutton>OK</guibutton>, a <command>cvs diff</command> command is issued to generate the difference file. A <guilabel>Save As</guilabel> dialogue 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 dialogue and return to the main view. </para> + + +<para>To generate the log that is the base for the <guilabel>CVS Log</guilabel> dialogue, &cervisia; issues the following command: </para> <para> -<screen -><command ->cvs log <replaceable ->file name</replaceable -></command -></screen> +<screen><command>cvs log <replaceable>file name</replaceable></command></screen> </para> </sect1> <sect1 id="browsinghistory"> -<title ->Browsing the History</title> +<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>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> +<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> +<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> +<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> +<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 dialogue</title> +<title>A screenshot of &cervisia;'s history dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="history.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s history dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="history.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s history dialogue</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> +<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> +<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 recognised by the regular expression matcher are: </para> +<para>Special characters recognised 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> +<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> @@ -2088,477 +847,164 @@ Changes in the repository </chapter> <chapter id="advancedusage"> -<title ->Advanced Usage</title> +<title>Advanced Usage</title> <sect1 id="updatingto"> -<title ->Updating to Tag, Branch or Date</title> +<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>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>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>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> +<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> +<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 dialogue</title> +<title>A screenshot of &cervisia;'s update to tag dialogue</title> <mediaobject> -<imageobject -><imagedata format="PNG" fileref="updatetag.png"/></imageobject> -<textobject -><phrase ->A screenshot of &cervisia;'s update to tag dialogue</phrase -></textobject> +<imageobject><imagedata format="PNG" fileref="updatetag.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s update to tag dialogue</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 edit 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> +<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 edit 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 edit 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> +<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 edit 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> +<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> +<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>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>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 dialogue, 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 dialogue 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> +<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 dialogue, 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 dialogue 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> +<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>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> +<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 dialogue 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 dialogue is </para> +<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 dialogue 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 dialogue is </para> <para> -<screen -><command ->cvs watch add -a commit <replaceable ->file names</replaceable -></command -></screen> +<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>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 dialogue you get here, the same options are offered as in the form you filled out when adding the watch. When you confirm this dialogue, &cervisia; issues the command </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 dialogue you get here, the same options are offered as in the form you filled out when adding the watch. When you confirm this dialogue, &cervisia; issues the command </para> <para> -<screen -><command ->cvs watch remove <replaceable ->file names</replaceable -></command -></screen> +<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>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>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> +<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>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>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> +<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>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> +<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>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> +<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> +<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 organisational 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> +<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 organisational 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> +<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>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> +<screen><command>cvs admin -u <replaceable>file names</replaceable></command></screen> </para> </sect1> @@ -2567,57 +1013,24 @@ Changes in the repository <chapter id="customization"> -<title ->Customising &cervisia;</title> +<title>Customising &cervisia;</title> -<para ->&cervisia; can be customised 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 dialogue which is available via <menuchoice -><guimenu ->Option</guimenu -><guimenuitem ->Settings...</guimenuitem -></menuchoice ->. </para> +<para>&cervisia; can be customised 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 dialogue which is available via <menuchoice><guimenu>Option</guimenu><guimenuitem>Settings...</guimenuitem></menuchoice>. </para> <sect1 id="customize-general"> -<title ->General</title> +<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> +<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> +<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> @@ -2625,81 +1038,28 @@ Changes in the repository </sect1> <sect1 id="customize-diff"> -<title ->Diff Viewer</title> +<title>Diff Viewer</title> <variablelist> <varlistentry id="customize-context"> -<term -><guilabel ->Number of context lines in the diff dialogue:</guilabel -></term> -<listitem -><para ->For the diff dialogue, &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> +<term><guilabel>Number of context lines in the diff dialogue:</guilabel></term> +<listitem><para>For the diff dialogue, &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> +<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 dialogue:</guilabel -></term> -<listitem -><para ->In the diff dialogue, 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> +<term><guilabel>Tab width in diff dialogue:</guilabel></term> +<listitem><para>In the diff dialogue, 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 dialogue, 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> +<term><guilabel>External diff frontend:</guilabel></term> +<listitem><para>When you use any of the features which show the diff dialogue, 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> @@ -2707,43 +1067,18 @@ Changes in the repository </sect1> <sect1 id="customize-status"> -<title ->Status</title> +<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> +<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> +<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> @@ -2751,62 +1086,23 @@ Changes in the repository </sect1> <sect1 id="customize-advanced"> -<title ->Advanced</title> +<title>Advanced</title> <variablelist> <varlistentry id="customize-timeout"> -<term -><guilabel ->Timeout after which a progress dialogue 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 dialogue which indicates that the command is still running and which allows you to abort it. Furthermore, this dialogue is used to show you error messages from &CVS;. As this dialogue 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> +<term><guilabel>Timeout after which a progress dialogue 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 dialogue which indicates that the command is still running and which allows you to abort it. Furthermore, this dialogue is used to show you error messages from &CVS;. As this dialogue 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> +<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 ->Utilise 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> +<term><guilabel>Utilise 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> @@ -2815,90 +1111,33 @@ Changes in the repository <sect1 id="customize-look"> -<title ->Look'n'feel</title> +<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 -> dialogue, to set the font used in the protocol window (this is the window showing the output of the <command ->cvs</command -> client). </para -></listitem> +<term><guilabel>Font for protocol window...</guilabel></term> +<listitem><para>Press this button to open the <guilabel>Set Font</guilabel> dialogue, 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 -> dialogue, to set the font used in the <link linkend="annotate" ->annotate view</link ->. </para -></listitem> +<term><guilabel>Font for annotate view...</guilabel></term> +<listitem><para>Press this button to open the <guilabel>Set Font</guilabel> dialogue, 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 -> dialogue, to set the font used in <link linkend="diff" ->diff dialogs</link ->. </para -></listitem> +<term><guilabel>Font for diff view...</guilabel></term> +<listitem><para>Press this button to open the <guilabel>Set Font</guilabel> dialogue, to set the font used in <link linkend="diff">diff dialogs</link>. </para></listitem> </varlistentry> <varlistentry id="customize-colors"> -<term -><guilabel ->Colours</guilabel -></term> -<listitem -><para ->Press the coloured buttons to open the <guilabel ->Select Colour</guilabel -> dialogue, to set the colour 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> +<term><guilabel>Colours</guilabel></term> +<listitem><para>Press the coloured buttons to open the <guilabel>Select Colour</guilabel> dialogue, to set the colour 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> +<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> @@ -2908,123 +1147,44 @@ Changes in the repository <chapter id="appendix"> -<title ->Appendix</title> +<title>Appendix</title> <sect1 id="ignoredfiles"> -<title ->Ignored Files</title> +<title>Ignored Files</title> -<para ->In its main file tree, &cervisia; does not display all files which are actually there. This is analogue 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> +<para>In its main file tree, &cervisia; does not display all files which are actually there. This is analogue 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> +<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> +<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> +<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> +<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> @@ -3032,252 +1192,80 @@ Changes in the repository <sect1 id="commandreference"> -<title ->Command Reference</title> +<title>Command Reference</title> <!-- File Menu --> <sect2 id="menufile"> -<title ->The File Menu</title> +<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> +<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> +<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> +<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> +<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> +<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> +<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 dialogue for the selected file which allows you to resolve merge conflicts in it. See <xref linkend="resolvingconflicts"/>. </para -></listitem> +<term><menuchoice><guimenu>File</guimenu><guimenuitem>Resolve...</guimenuitem> </menuchoice></term> +<listitem><para>Opens a dialogue 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> +<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> +<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> +<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> +<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> +<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> +<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> @@ -3287,258 +1275,81 @@ Changes in the repository <!-- View Menu --> <sect2 id="menuview"> -<title ->The View Menu</title> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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 without visible entries are hidden in the main tree view. See <xref linkend="mainscreen"/>. </para -></listitem> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Hide Empty Folders</guimenuitem> </menuchoice></term> +<listitem><para>Determines whether 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> +<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> +<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> @@ -3548,224 +1359,77 @@ Changes in the repository <!-- Advanced Menu --> <sect2 id="menuadvanced"> -<title ->The Advanced Menu</title> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> @@ -3775,69 +1439,28 @@ Changes in the repository <!-- Repository Menu --> <sect2 id="menurepository"> -<title ->The Repository Menu</title> +<title>The Repository Menu</title> <variablelist> <varlistentry> -<term -><menuchoice -><guimenu ->Repository</guimenu -><guimenuitem ->Create...</guimenuitem -> </menuchoice -></term> -<listitem -><para ->Opens a dialogue which allows you to create a new local repository. See <xref linkend="accessing-repository"/>. </para -></listitem> +<term><menuchoice><guimenu>Repository</guimenu><guimenuitem>Create...</guimenuitem> </menuchoice></term> +<listitem><para>Opens a dialogue 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 dialogue which allows you to checkout a module from a repository. See <xref linkend="checkingout"/>. </para -></listitem> +<term><menuchoice><guimenu>Repository</guimenu><guimenuitem>Checkout...</guimenuitem> </menuchoice></term> +<listitem><para>Opens a dialogue 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 dialogue which allows you to import a package into the repository. See <xref linkend="importing"/>. </para -></listitem> +<term><menuchoice><guimenu>Repository</guimenu><guimenuitem>Import...</guimenuitem> </menuchoice></term> +<listitem><para>Opens a dialogue 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> +<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> @@ -3846,164 +1469,53 @@ Changes in the repository <!-- Settings Menu --> <sect2 id="menuoptions"> -<title ->The Settings Menu</title> +<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> +<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> +<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> +<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> +<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> +<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> +<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 dialogue for configuring keybindings. </para -></listitem> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem> </menuchoice></term> +<listitem><para>Opens a dialogue for configuring keybindings. </para></listitem> </varlistentry> <varlistentry> -<term -><menuchoice -><guimenu ->Settings</guimenu -><guimenuitem ->Configure Toolbars...</guimenuitem -> </menuchoice -></term> -<listitem -><para ->Opens a dialogue for configuring &cervisia;'s toolbars. </para -></listitem> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem> </menuchoice></term> +<listitem><para>Opens a dialogue for configuring &cervisia;'s toolbars. </para></listitem> </varlistentry> <varlistentry> -<term -><menuchoice -><guimenu ->Settings</guimenu -><guimenuitem ->Configure Cervisia...</guimenuitem -> </menuchoice -></term> -<listitem -><para ->Opens a dialogue for customising &cervisia;. </para -></listitem> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Cervisia...</guimenuitem> </menuchoice></term> +<listitem><para>Opens a dialogue for customising &cervisia;. </para></listitem> </varlistentry> </variablelist> @@ -4012,88 +1524,33 @@ Changes in the repository <!-- Help --> <sect2 id="menuhelp"> -<title ->The Help Menu</title> +<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> +<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 dialogue. </para -></listitem> +<term><menuchoice><guimenu>Help</guimenu><guimenuitem>Report Bug...</guimenuitem> </menuchoice></term> +<listitem><para>Opens the Bug report dialogue. </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> +<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> +<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> +<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> @@ -4106,7 +1563,6 @@ Changes in the repository <chapter id="credits-and-licenses"> -<title ->Credits And Licenses</title> +<title>Credits And Licenses</title> &underFDL; </chapter> </book> diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/catman.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/catman.docbook index e0e16896d11..df408454d82 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/catman.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/catman.docbook @@ -1,6 +1,5 @@ <!-- <?xml version="1.0" ?> -<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" -> --> +<!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 --> @@ -11,57 +10,27 @@ <!-- Fill in this section if this document has a different author --> <authorgroup> <author> -<personname -><firstname -></firstname -><surname -></surname -></personname> +<personname><firstname></firstname><surname></surname></personname> </author> </authorgroup> -<othercredit role="translator" -><firstname ->Malcolm</firstname -><surname ->Hunter</surname -><affiliation -><address -><email ->malcolm.hunter@gmx.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Malcolm</firstname><surname>Hunter</surname><affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </chapterinfo> -<title ->Using &cataloguemanager;</title> +<title>Using &cataloguemanager;</title> <anchor id="catalogmanager"/> <screenshot> -<screeninfo ->Screenshot of &cataloguemanager;</screeninfo> +<screeninfo>Screenshot of &cataloguemanager;</screeninfo> <mediaobject> <imageobject> <imagedata fileref="snap_catalogmanager.png" format="PNG"/> </imageobject> -<textobject -><phrase ->Screenshot of &cataloguemanager;</phrase -></textobject> +<textobject><phrase>Screenshot of &cataloguemanager;</phrase></textobject> </mediaobject> </screenshot> -<para ->The Catalogue 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> -<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> +<para>The Catalogue 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> +<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> @@ -70,8 +39,7 @@ <imageobject> <imagedata fileref="catalogmanager_ok.png" format="PNG"/> </imageobject> -</inlinemediaobject -> All the messages in this file are translated.</para> +</inlinemediaobject> All the messages in this file are translated.</para> </listitem> <listitem> <para> @@ -79,8 +47,7 @@ <imageobject> <imagedata fileref="catalogmanager_needwork.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Some of the messages in this file are fuzzy or untranslated </para> +</inlinemediaobject> Some of the messages in this file are fuzzy or untranslated </para> </listitem> <listitem> <para> @@ -88,10 +55,7 @@ <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> +</inlinemediaobject> This file does not exist in the folder of the <acronym>PO</acronym> files. </para> </listitem> <listitem> <para> @@ -99,8 +63,7 @@ <imageobject> <imagedata fileref="catalogmanager_broken.png" format="PNG"/> </imageobject> -</inlinemediaobject -> This file contains syntax errors. </para> +</inlinemediaobject> This file contains syntax errors. </para> </listitem> <listitem> <para> @@ -108,106 +71,43 @@ <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> +</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 &cataloguemanager; by <menuchoice -><guimenu ->Settings</guimenu -><guimenuitem -> Configure &cataloguemanager;...</guimenuitem -></menuchoice ->. See section <link linkend="preferences-catalogmanager" ->Preferences</link -> for more details.</para> +<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 &cataloguemanager; by <menuchoice><guimenu>Settings</guimenu><guimenuitem> Configure &cataloguemanager;...</guimenuitem></menuchoice>. See section <link linkend="preferences-catalogmanager">Preferences</link> for more details.</para> <sect1 id="catman-features"> -<title ->&cataloguemanager; Features</title> -<para ->Besides the main feature for opening the files in &kbabel; &cataloguemanager; supports number of other features for maintaining a tree of <acronym ->PO</acronym ->-files. </para> +<title>&cataloguemanager; Features</title> +<para>Besides the main feature for opening the files in &kbabel; &cataloguemanager; 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. &cataloguemanager; supports this feature with a tight integration with &kbabel; </para> +<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. &cataloguemanager; supports this feature with a tight integration with &kbabel; </para> </sect2> <sect2 id="catman-statistics"> -<title ->Statistics</title> -<para ->&cataloguemanager; 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> +<title>Statistics</title> +<para>&cataloguemanager; 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> +<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 &cataloguemanager; cannot provide any functionality you would like to use, you can extend it by defining your own commands. </para> -<para ->There are two sets of commands. One for folders and one for single files. You can set them in <link linkend="preferences-catalogmanager" ->configuration dialogue </link -> and access by pressing &RMB; on an entry in the file list.</para> +<title>User-defined commands</title> +<para>Because &cataloguemanager; cannot provide any functionality you would like to use, you can extend it by defining your own commands. </para> +<para>There are two sets of commands. One for folders and one for single files. You can set them in <link linkend="preferences-catalogmanager">configuration dialogue </link> and access by pressing &RMB; on an entry in the file list.</para> </sect2> </sect1> diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/dictionaries.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/dictionaries.docbook index 261d6c6ecfa..f0e7fe01f25 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/dictionaries.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/dictionaries.docbook @@ -1,6 +1,5 @@ <!-- <?xml version="1.0" ?> -<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" -> --> +<!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 --> @@ -11,615 +10,284 @@ <!-- Fill in this section if this document has a different author --> <authorgroup> <author> -<personname -><firstname -></firstname -><surname -></surname -></personname> +<personname><firstname></firstname><surname></surname></personname> </author> </authorgroup> -<othercredit role="translator" -><firstname ->Malcolm</firstname -><surname ->Hunter</surname -><affiliation -><address -><email ->malcolm.hunter@gmx.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Malcolm</firstname><surname>Hunter</surname><affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </chapterinfo> -<title ->Dictionaries</title> +<title>Dictionaries</title> -<para ->&kbabel; has 3 modes which can be used to search translated <acronym ->PO</acronym -> message strings:</para> +<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> + <para>Searching translation, using a translation database </para> </listitem> <listitem> - <para ->Rough translation </para> + <para>Rough translation </para> </listitem> <listitem> - <para ->&kbabeldict; </para> + <para>&kbabeldict; </para> </listitem> </itemizedlist> <sect1 id="database"> <!-- FIXME: settings --> -<title ->Translation database</title> +<title>Translation database</title> -<para ->Translation database allows you to store translations in a database based on Berkeley Database II, &ie; it is stored in a binary file on your disk. The database guarantees fast searching in a large number of translations.</para> +<para>Translation database allows you to store translations in a database based on Berkeley Database II, &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> +<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> +<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> +<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 dialogue or you can turn on automatic addition of every translated messages on the same tab.</para> +<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 dialogue 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> +<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> + <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> + <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> + <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> + <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> + <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> + <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> + <term><guibutton>Case sensitive</guibutton></term> <listitem> - <para ->Distinguish case of letters when searching the text. </para> + <para>Distinguish case of letters when searching the text. </para> </listitem> </varlistentry> <varlistentry> - <term -><guibutton ->Normalise white space</guibutton -></term> + <term><guibutton>Normalise 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> + <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> + <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> + <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> + <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> + <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> +<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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <term><guilabel>Local characters for regular expressions</guilabel></term> <listitem> - <para ->Characters to be considered part of regular expressions. </para> + <para>Characters to be considered part of regular expressions. </para> </listitem> </varlistentry> </variablelist> <note> -<para ->Two-word substitution is not implemented yet. </para> +<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 dialogue 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> +<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 dialogue 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> +<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> +<textobject><phrase>Filling the database by existing PO-files</phrase></textobject> </mediaobject> -</screenshot -></sect2> +</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> +<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 romanic languages to have similar words, similarly for anglosaxon and slavonic ones.</para> - -<para ->For example, say I wanted to translate the word <quote ->on</quote ->, from <filename ->tdelibs.po</filename ->, into Romanian but have no idea. I look in the same file for French and find <quote ->actif</quote ->, and in the Spanish one find <quote ->activado</quote ->. So, I conclude that the best one in Romanian will be <quote ->active</quote ->. &kbabel; automates this task. Currently you can define only one auxiliary file to search.</para> +<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 romanic languages to have similar words, similarly for anglosaxon and slavonic ones.</para> + +<para>For example, say I wanted to translate the word <quote>on</quote>, from <filename>tdelibs.po</filename>, into Romanian but have no idea. I look in the same file for French and find <quote>actif</quote>, and in the Spanish one find <quote>activado</quote>. So, I conclude that the best one in Romanian will be <quote>active</quote>. &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 -> dialogue 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> +<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> dialogue 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, tdelibs, konqueror and so on. </para -></listitem> + <term>@PACKAGE@</term> + <listitem><para>The name of application or package currently being translated. For example, it can expand to kbabel, tdelibs, konqueror and so on. </para></listitem> </varlistentry> <varlistentry> - <term ->@LANG@</term> - <listitem -><para ->The language code. For example can expand to: en_GB, de, ro, fr etc. </para -></listitem> + <term>@LANG@</term> + <listitem><para>The language code. For example can expand to: en_GB, 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> + <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> - -<para ->First step is to download a very fresh <filename ->tde-i18n-fr.tar.bz2</filename -> from the <ulink url="ftp://ftp.kde.org/pub/kde/snapshots/tde-i18n" ->&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/tde-i18n/fr</filename ->.</para> - -<para ->My <acronym ->PO</acronym -> sources folder is in <filename ->/home/clau/cvs-cvs.kde.org/tde-i18n/ro</filename ->. Don't 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 -> dialogue.</para> +<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> + +<para>First step is to download a very fresh <filename>tde-i18n-fr.tar.bz2</filename> from the <ulink url="ftp://ftp.kde.org/pub/kde/snapshots/tde-i18n">&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/tde-i18n/fr</filename>.</para> + +<para>My <acronym>PO</acronym> sources folder is in <filename>/home/clau/cvs-cvs.kde.org/tde-i18n/ro</filename>. Don't 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> dialogue.</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> +<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 -> dialogue 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> +<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> dialogue 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: en_GB, de, ro, fr etc. </para -></listitem> + <term>@LANG@</term> + <listitem><para>The language code. For example can expand to: en_GB, 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> +<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> -<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/tde-i18n" ->&kde; &FTP; site</ulink ->. </para> +<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/tde-i18n">&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> +<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> + <term><guilabel>Case sensitive</guilabel></term> <listitem> - <para ->If the matching of message in compendium should distinguish between uppercase and lowercase letters. </para> + <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> + <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> + <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> + <term><guilabel>Only whole words</guilabel></term> <listitem> - <para ->If the matching text should start and end at the boundaries of words. </para> + <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 -> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/faq.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/faq.docbook index 1109bb9abcb..7da2eeaa399 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/faq.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/faq.docbook @@ -1,6 +1,5 @@ <!-- <?xml version="1.0" ?> -<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" -> --> +<!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 --> @@ -10,85 +9,31 @@ <!-- Fill in this section if this document has a different author --> <authorgroup> <author> -<personname -><firstname -></firstname -><surname -></surname -></personname> +<personname><firstname></firstname><surname></surname></personname> </author> </authorgroup> -<othercredit role="translator" -><firstname ->Malcolm</firstname -><surname ->Hunter</surname -><affiliation -><address -><email ->malcolm.hunter@gmx.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Malcolm</firstname><surname>Hunter</surname><affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </chapterinfo> -<title ->Questions and Answers</title> +<title>Questions and Answers</title> <qandaset> <qandaentry> <question> - <para ->Why does &kbabel; show question marks when entering language specific characters? </para> + <para>Why does &kbabel; show question marks when entering language specific characters? </para> </question> <answer> - <para ->This is a problem with your locale settings. The following might help: Exit &kbabel;, in a shell set the environment variable <envar ->LANG</envar -> to a locale, valid for your language. If you use <command ->bash</command -> do <userinput -><command ->export <envar ->LANG</envar ->=<replaceable ->change this</replaceable -></command -></userinput ->. For example, when you use german characters, do <userinput -><command ->export <envar ->LANG</envar ->=de_DE.88591</command -></userinput ->. Then start &kbabel; from this shell. If the problem is gone, insert this command in your <filename ->~/.profile</filename ->. </para> + <para>This is a problem with your locale settings. The following might help: Exit &kbabel;, in a shell set the environment variable <envar>LANG</envar> to a locale, valid for your language. If you use <command>bash</command> do <userinput><command>export <envar>LANG</envar>=<replaceable>change this</replaceable></command></userinput>. For example, when you use german characters, do <userinput><command>export <envar>LANG</envar>=de_DE.88591</command></userinput>. Then start &kbabel; from this shell. If the problem is gone, insert this command in your <filename>~/.profile</filename>. </para> </answer> </qandaentry> <qandaentry> <question> - <para ->Why does &kbabel; show question marks instead of language specific characters after loading a <acronym ->PO</acronym -> file?</para> + <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> + <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> </qandaset> diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/glossary.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/glossary.docbook index 00a4beaa0b1..e264d9c884f 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/glossary.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/glossary.docbook @@ -1,6 +1,5 @@ <!-- <?xml version="1.0" ?> -<!DOCTYPE glossary PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" -> --> +<!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 --> @@ -10,249 +9,83 @@ <!-- Fill in this section if this document has a different author --> <authorgroup> <author> -<personname -><firstname -></firstname -><surname -></surname -></personname> +<personname><firstname></firstname><surname></surname></personname> </author> </authorgroup> -<othercredit role="translator" -><firstname ->Alex</firstname -><surname ->Walker</surname -><affiliation -><address -><email ->alex@x3ja.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Alex</firstname><surname>Walker</surname><affiliation><address><email>alex@x3ja.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </glossaryinfo> -<title ->Glossary</title> +<title>Glossary</title> -<glossdiv -><title ->A</title> +<glossdiv><title>A</title> <glossentry id="gloss-auxiliary"> - <glossterm ->Auxiliary file</glossterm> + <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> + <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> +<glossdiv><title>C</title> <glossentry id="gloss-compendium"> - <glossterm ->Compendium file</glossterm> + <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> + <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> +<glossdiv><title>F</title> <glossentry id="fuzzy"> - <glossterm ->Fuzzy</glossterm> + <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> + <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 ->Internationalisation</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 ->internationalisation</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> +<glossdiv><title>I</title> + <glossentry id="i18n"><glossterm>Internationalisation</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>internationalisation</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 ->Localisation</glossterm -> <acronym ->l10n</acronym -> <glossdef> - <para ->is the operation by which an application already internationalised is made to process input and output in a fashion desired by some cultural and language habits. The word <quote ->localisation</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> +<glossdiv><title>L</title> + <glossentry id="l10n"><glossterm>Localisation</glossterm> <acronym>l10n</acronym> <glossdef> + <para>is the operation by which an application already internationalised is made to process input and output in a fashion desired by some cultural and language habits. The word <quote>localisation</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 organised as a database to minimise 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> +<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 organised as a database to minimise 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> + <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 introduces 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> + <glossentry id="msgstr"><glossterm>Message String</glossterm> <acronym>msgstr</acronym> <glossdef> + <para><acronym>msgstr</acronym> is the keyword which introduces 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> +<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 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> diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/index.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/index.docbook index 039381641ca..fa621352ec6 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/index.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/index.docbook @@ -11,89 +11,47 @@ <!ENTITY kappname "&kbabel;"> <!ENTITY package "tdesdk"> <!ENTITY % addindex "IGNORE"> - <!ENTITY % British-English "INCLUDE" -> <!-- change language only here --> + <!ENTITY % British-English "INCLUDE"> <!-- change language only here --> ]> <book lang="&language;"> <bookinfo> -<title ->The &kbabel; Handbook</title> +<title>The &kbabel; Handbook</title> <authorgroup> -<author ->&Stanislav.Visnovsky; &Stanislav.Visnovsky.mail; </author> -<author ->&Matthias.Kiefer; </author> -<othercredit role="translator" -><firstname ->Malcolm</firstname -><surname ->Hunter</surname -><affiliation -><address -><email ->malcolm.hunter@gmx.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<author>&Stanislav.Visnovsky; &Stanislav.Visnovsky.mail; </author> +<author>&Matthias.Kiefer; </author> +<othercredit role="translator"><firstname>Malcolm</firstname><surname>Hunter</surname><affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </authorgroup> -<date ->2003-09-18</date> -<releaseinfo ->3.1.91</releaseinfo> +<date>2003-09-18</date> +<releaseinfo>3.1.91</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 &cataloguemanager; and a dictionary for translators &kbabeldict;. It supports many advanced features and it lets you customise many options. </para> +<para>&kbabel; is a suite of of an advanced and easy to use <acronym>PO</acronym> file editor comprising &kbabel;, a multi functional &cataloguemanager; and a dictionary for translators &kbabeldict;. It supports many advanced features and it lets you customise many options. </para> </abstract> <keywordset> -<keyword ->KDE</keyword> -<keyword ->KBabel</keyword> -<keyword ->catalogmanager</keyword> -<keyword ->tdesdk</keyword> -<keyword ->gettext</keyword> -<keyword ->translation</keyword> -<keyword ->i18n</keyword> -<keyword ->l10n</keyword> +<keyword>KDE</keyword> +<keyword>KBabel</keyword> +<keyword>catalogmanager</keyword> +<keyword>tdesdk</keyword> +<keyword>gettext</keyword> +<keyword>translation</keyword> +<keyword>i18n</keyword> +<keyword>l10n</keyword> </keywordset> </bookinfo> <chapter id="introduction"> -<title ->Introduction</title> - -<para ->&kbabel; is an advanced and easy to use <acronym ->PO</acronym -> file (&GNU; gettext message catalogues) 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. &cataloguemanager; 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 organised and consistent across all translations. </para> +<title>Introduction</title> + +<para>&kbabel; is an advanced and easy to use <acronym>PO</acronym> file (&GNU; gettext message catalogues) 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. &cataloguemanager; 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 organised and consistent across all translations. </para> </chapter> @@ -107,68 +65,47 @@ <chapter id="credits"> -<title ->Credits and Licence</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> +<title>Credits and Licence</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><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>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.0 Copyright © 2002 &Stanislav.Visnovsky; &Stanislav.Visnovsky.mail;</para> -<para ->Malcolm Hunter<email ->malcolm.hunter@gmx.co.uk</email -></para -> +<para>Malcolm Hunter<email>malcolm.hunter@gmx.co.uk</email></para> &underFDL; &underGPL; </chapter> &glossary; <appendix id="installation"> -<title ->Installation</title> +<title>Installation</title> <sect1 id="getting-kbabel"> -<title ->How to obtain &kbabel;</title> +<title>How to obtain &kbabel;</title> &install.intro.documentation; </sect1> <sect1 id="requirements"> -<title ->Requirements</title> +<title>Requirements</title> -<para ->In order to successfully use &kbabel;, you need &kde; 3.x. </para> +<para>In order to successfully use &kbabel;, you need &kde; 3.x. </para> -<para ->All required libraries as well as &kbabel; itself can be found on &kde-ftp;. </para> +<para>All required libraries as well as &kbabel; itself can be found on &kde-ftp;. </para> -<para ->If you want to use the translation database, you need Berkeley Database II. </para> +<para>If you want to use the translation database, you need Berkeley Database II. </para> </sect1> <sect1 id="compilation"> -<title ->Compilation and Installation</title> +<title>Compilation and Installation</title> &install.compile.documentation; </sect1> </appendix> diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/kbabeldict.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/kbabeldict.docbook index 397d20ad65c..c56e9e54e68 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/kbabeldict.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/kbabeldict.docbook @@ -1,6 +1,5 @@ <!-- <?xml version="1.0" ?> -<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" -> --> +<!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 --> @@ -10,82 +9,39 @@ <!-- Fill in this section if this document has a different author --> <authorgroup> <author> -<personname -><firstname -></firstname -><surname -></surname -></personname> +<personname><firstname></firstname><surname></surname></personname> </author> </authorgroup> -<othercredit role="translator" -><firstname ->Malcolm</firstname -><surname ->Hunter</surname -><affiliation -><address -><email ->malcolm.hunter@gmx.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Malcolm</firstname><surname>Hunter</surname><affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </chapterinfo> -<title ->Using &kbabeldict;</title> +<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> +<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> +<screeninfo>Screenshot of &kbabeldict;</screeninfo> <mediaobject> <imageobject> <imagedata fileref="snap_kbabeldict.png" format="PNG"/> </imageobject> -<textobject -><phrase ->Screenshot of &kbabeldict;</phrase -></textobject> +<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> +<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> +<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> +<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 dialogue with credits for &kbabeldict; and the modules themselves. </para> +<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 dialogue 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> +<para>For description of the standard modules and their settings see <xref linkend="dictionaries"/>. </para> </note> </chapter> <!-- diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/menu.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/menu.docbook index b2cfe879f2d..e559271f14e 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/menu.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/menu.docbook @@ -1,6 +1,5 @@ <!-- <?xml version="1.0" ?> -<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" -> --> +<!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 --> @@ -11,218 +10,116 @@ <!-- Fill in this section if this document has a different author --> <authorgroup> <author> -<personname -><firstname ->Andrew</firstname -><surname ->Coles</surname -></personname> +<personname><firstname>Andrew</firstname><surname>Coles</surname></personname> </author> </authorgroup> -<othercredit role="translator" -><firstname ->Malcolm</firstname -><surname ->Hunter</surname -><affiliation -><address -><email ->malcolm.hunter@gmx.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Malcolm</firstname><surname>Hunter</surname><affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </chapterinfo> -<title ->Command Reference</title> +<title>Command Reference</title> <sect1 id="kbabel-menu"> -<title ->The &kbabel; menu</title> +<title>The &kbabel; menu</title> <sect2> -<title ->The File Menu</title> +<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> + <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> + <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> + <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> + <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> + <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> + <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> + <menuchoice><guimenu>File</guimenu> <guimenuitem>Save As</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Saves the current PO file under a new name </action> + <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> + <menuchoice><guimenu>File</guimenu> <guimenuitem>Save Special</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Displays the Save Settings dialogue and then saves the current PO file under a new name </action> + <action>Displays the Save Settings dialogue 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> + <menuchoice><guimenu>File</guimenu> <guimenuitem>Revert</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Loads the last saved version of the current PO file </action> + <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> + <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> + <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> + <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> + <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> + <menuchoice><guimenu>File</guimenu> <guimenuitem>New Window</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Opens a new empty window </action> + <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> + <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> + <action>Quits &kbabel; editor </action> </para> </listitem> </varlistentry> @@ -230,345 +127,162 @@ </sect2> <sect2> -<title ->The Edit Menu</title> +<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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Select All</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Selects all text in the translation edit box </action> + <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> + <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 dialogue for searching for strings in the current PO file </action> + <action>Opens a Find dialogue 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> + <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> + <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> + <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 dialogue to search for and replace strings in the current PO file </action> + <action>Opens the Replace dialogue 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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> @@ -576,318 +290,152 @@ <sect2> -<title ->The Go Menu</title> +<title>The Go Menu</title> <variablelist> <varlistentry> <term> - <menuchoice -><shortcut -> <keycap ->Page Up</keycap -> </shortcut -> <guimenu ->Go</guimenu -> <guimenuitem ->Previous</guimenuitem -> </menuchoice> + <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> + <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> + <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 -> + <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> + <menuchoice><guimenu>Go</guimenu> <guimenuitem>Go to...</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Opens a dialogue to jump to a specific entry number within the PO file. </action -> + <action>Opens a dialogue 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> + <menuchoice><guimenu>Go</guimenu> <guimenuitem>First Entry</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Jumps to the first entry in the PO file. </action -> + <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> + <menuchoice><guimenu>Go</guimenu> <guimenuitem>Last Entry</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Jumps to the last entry in the PO file. </action> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <para><action> Jump to previous visited entry</action> in PO file. </para> </listitem> </varlistentry> </variablelist> @@ -895,138 +443,70 @@ <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> +<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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> @@ -1035,725 +515,352 @@ <sect2> -<title ->The Tools Menu</title> +<title>The Tools Menu</title> <variablelist> <varlistentry> <term> - <menuchoice -><guimenu ->Tools</guimenu -> <guimenuitem ->Spelling</guimenuitem -> <guimenuitem ->Spell check...</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Spelling</guimenuitem> <guimenuitem>Spell check...</guimenuitem> </menuchoice> </term> <listitem> - <para -><action -> Display the spell-check configuration dialogue.</action -> After you have chosen the desired options, hit <guibutton ->OK</guibutton -> and the normal spell-checking dialogue will appear. </para> + <para><action> Display the spell-check configuration dialogue.</action> After you have chosen the desired options, hit <guibutton>OK</guibutton> and the normal spell-checking dialogue will appear. </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Tools</guimenu -> <guimenuitem ->Spelling</guimenuitem -> <guimenuitem ->Check All...</guimenuitem -> </menuchoice> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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-miscellaneous" ->Miscellaneous</link -> section below to find out how to change a keyboard accelerator. </para> + <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-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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Diff</guimenuitem> <guimenuitem>Diffmode</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Toggle difference mode. </action> + <action>Toggle difference mode. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Tools</guimenu -> <guimenuitem ->Rough Translation...</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Rough Translation...</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Invoke rough-translation dialogue for automated translation. </action> + <action>Invoke rough-translation dialogue for automated translation. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Tools</guimenu -> <guimenuitem ->Catalogue Manager...</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Catalogue Manager...</guimenuitem> </menuchoice> </term> <listitem> - <para ->Open &catalogmanager;. Read <link linkend="using-catalogmanager" ->&catalogmanager;</link -> section for more details. </para> + <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> +<title>The Settings Menu</title> <variablelist> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Show Toolbar</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Show Toolbar</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->When checked, the standard toolbar is displayed. </action> + <action>When checked, the standard toolbar is displayed. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Show Statusbar</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Show Statusbar</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->When checked, the bottom statusbar is displayed. </action> + <action>When checked, the bottom statusbar is displayed. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Show Navigation Bar</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Show Navigation Bar</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->When checked, the navigation bar is displayed. </action> + <action>When checked, the navigation bar is displayed. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Show Comments</guimenuitem -> </menuchoice> + <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> + <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> + <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> + <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> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Key Bindings...</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Opens a configure dialogue for binding keys to actions. This will let you to customise the default key bindings to suite your needs. </action> + <action>Opens a configure dialogue for binding keys to actions. This will let you to customise the default key bindings to suite your needs. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Configure Toolbars...</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Toolbars...</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Standard toolbar-configuration dialogue will open. You can choose which actions will go in which toolbars and what toolbar to customise. </action> + <action>Standard toolbar-configuration dialogue will open. You can choose which actions will go in which toolbars and what toolbar to customise. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Configure Kbabel...</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Kbabel...</guimenuitem> </menuchoice> </term> <listitem> - <para ->All &kbabel;-specific settings go here. Please read the <link linkend="preferences-kbabel" ->Preferences</link -> section for specific topics. </para> + <para>All &kbabel;-specific settings go here. Please read the <link linkend="preferences-kbabel">Preferences</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> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Dictionary</guimenuitem> <guimenuitem>KDE Database Search Engine</guimenuitem> </menuchoice> </term> <listitem> - <para ->Open dialogue for &kde; Database Search Engine configuration. </para> + <para>Open dialogue for &kde; Database Search Engine configuration. </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Configure Dictionary</guimenuitem -> <guimenuitem ->PO Auxiliary</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Dictionary</guimenuitem> <guimenuitem>PO Auxiliary</guimenuitem> </menuchoice> </term> <listitem> - <para -><action -> Open dialogue</action -> for <acronym ->PO</acronym -> auxiliary file configuration. </para> + <para><action> Open dialogue</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> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Dictionary</guimenuitem> <guimenuitem>PO Compendium</guimenuitem> </menuchoice> </term> <listitem> - <para -><action -> Open dialogue</action -> for <acronym ->PO</acronym -> compendium file configuration. </para> + <para><action> Open dialogue</action> for <acronym>PO</acronym> compendium file configuration. </para> </listitem> </varlistentry> </variablelist> </sect2> <sect2> -<title ->The Help Menu</title> +<title>The Help Menu</title> <variablelist> <varlistentry> <term> - <menuchoice -><shortcut -> <keycap ->F1</keycap -> </shortcut -> <guimenu ->Help</guimenu -> <guimenuitem ->Contents</guimenuitem -> </menuchoice> + <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> + <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> + <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> + <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> + <menuchoice><guimenu>Help</guimenu> <guimenuitem>Gettext Info</guimenuitem> </menuchoice> </term> <listitem> - <para -><action -> Open the gettext manual page</action -> in the &kde; Help Centre. This package of tools helps the in process of handling <acronym ->POT</acronym -> and <acronym ->PO</acronym -> files. </para> + <para><action> Open the gettext manual page</action> in the &kde; Help Centre. 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> + <menuchoice><guimenu>Help</guimenu> <guimenuitem>Report Bug...</guimenuitem> </menuchoice> </term> <listitem> - <para -><action -> This will open a standard error-reporting dialogue </action -> for &kde; It is useful if you experience abnormal behaviour of &kbabel;. &kbabel;'s developer will be glad to receive any comments, wishes, and bug reports. </para> + <para><action> This will open a standard error-reporting dialogue </action> for &kde; It is useful if you experience abnormal behaviour 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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <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> + <action>Display a message box with information about people who made searching in compendium file possible. </action> </para> </listitem> </varlistentry> @@ -1762,12 +869,10 @@ </sect1> <sect1 id="kbabel-toolbars"> -<title ->The &kbabel; toolbars</title> +<title>The &kbabel; toolbars</title> <sect2 id="standard-toolbar"> -<title ->Standard Toolbar</title> +<title>Standard Toolbar</title> <variablelist> <varlistentry> <term> @@ -1775,13 +880,9 @@ <imageobject> <imagedata fileref="fileopen.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Open </term> +</inlinemediaobject> Open </term> <listitem> - <para ->Load <acronym ->PO</acronym -> file in &kbabel; for editing.</para> + <para>Load <acronym>PO</acronym> file in &kbabel; for editing.</para> </listitem> </varlistentry> <varlistentry> @@ -1790,13 +891,9 @@ <imageobject> <imagedata fileref="filesave.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Save </term> +</inlinemediaobject> Save </term> <listitem> - <para ->Save current <acronym ->PO</acronym -> file if it is modified.</para> + <para>Save current <acronym>PO</acronym> file if it is modified.</para> </listitem> </varlistentry> <varlistentry> @@ -1805,11 +902,9 @@ <imageobject> <imagedata fileref="undo.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Undo </term> +</inlinemediaobject> Undo </term> <listitem> - <para ->Undo last operation.</para> + <para>Undo last operation.</para> </listitem> </varlistentry> <varlistentry> @@ -1818,11 +913,9 @@ <imageobject> <imagedata fileref="redo.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Redo </term> +</inlinemediaobject> Redo </term> <listitem> - <para ->Redo last operation.</para> + <para>Redo last operation.</para> </listitem> </varlistentry> <varlistentry> @@ -1831,11 +924,9 @@ <imageobject> <imagedata fileref="editcut.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Cut </term> +</inlinemediaobject> Cut </term> <listitem> - <para ->Cut selected text and move it to the clipboard.</para> + <para>Cut selected text and move it to the clipboard.</para> </listitem> </varlistentry> <varlistentry> @@ -1844,11 +935,9 @@ <imageobject> <imagedata fileref="editcopy.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Copy </term> +</inlinemediaobject> Copy </term> <listitem> - <para ->Copy selected text to the clipboard.</para> + <para>Copy selected text to the clipboard.</para> </listitem> </varlistentry> <varlistentry> @@ -1857,11 +946,9 @@ <imageobject> <imagedata fileref="editpaste.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Paste </term> +</inlinemediaobject> Paste </term> <listitem> - <para ->Paste text from clipboard at the current cursor position.</para> + <para>Paste text from clipboard at the current cursor position.</para> </listitem> </varlistentry> <varlistentry> @@ -1870,11 +957,9 @@ <imageobject> <imagedata fileref="find.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Find </term> +</inlinemediaobject> Find </term> <listitem> - <para ->Find specified string in current PO-file.</para> + <para>Find specified string in current PO-file.</para> </listitem> </varlistentry> <varlistentry> @@ -1883,11 +968,9 @@ <imageobject> <imagedata fileref="previous.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Previous </term> +</inlinemediaobject> Previous </term> <listitem> - <para ->Skip to previous entry in PO-file.</para> + <para>Skip to previous entry in PO-file.</para> </listitem> </varlistentry> <varlistentry> @@ -1896,13 +979,9 @@ <imageobject> <imagedata fileref="next.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Next </term> +</inlinemediaobject> Next </term> <listitem> - <para ->Skip to next entry in <acronym ->PO</acronym -> file.</para> + <para>Skip to next entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -1911,15 +990,9 @@ <imageobject> <imagedata fileref="msgid2msgstr.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Copy <acronym ->msgid</acronym -> to <acronym ->msgstr</acronym -> </term> +</inlinemediaobject> Copy <acronym>msgid</acronym> to <acronym>msgstr</acronym> </term> <listitem> - <para ->Copy original string to translated string edit box.</para> + <para>Copy original string to translated string edit box.</para> </listitem> </varlistentry> <varlistentry> @@ -1928,15 +1001,9 @@ <imageobject> <imagedata fileref="transsearch.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Search Translations </term> +</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> + <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> @@ -1945,11 +1012,9 @@ <imageobject> <imagedata fileref="stop.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Stop </term> +</inlinemediaobject> Stop </term> <listitem> - <para ->Stop current search-in-progress.</para> + <para>Stop current search-in-progress.</para> </listitem> </varlistentry> <varlistentry> @@ -1958,19 +1023,16 @@ <imageobject> <imagedata fileref="catalogmanager.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Catalogue Manager </term> +</inlinemediaobject> Catalogue Manager </term> <listitem> - <para ->Open Catalogue Manager window.</para> + <para>Open Catalogue Manager window.</para> </listitem> </varlistentry> </variablelist> </sect2> <sect2 id="navigation-toolbar"> -<title ->Navigation Toolbar</title> +<title>Navigation Toolbar</title> <variablelist> <varlistentry> <term> @@ -1978,13 +1040,9 @@ <imageobject> <imagedata fileref="previous.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Previous </term> +</inlinemediaobject> Previous </term> <listitem> - <para ->Skip to previous entry in <acronym ->PO</acronym -> file.</para> + <para>Skip to previous entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -1993,13 +1051,9 @@ <imageobject> <imagedata fileref="next.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Next </term> +</inlinemediaobject> Next </term> <listitem> - <para ->Skip to next entry in <acronym ->PO</acronym -> file.</para> + <para>Skip to next entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2008,13 +1062,9 @@ <imageobject> <imagedata fileref="top.png" format="PNG"/> </imageobject> -</inlinemediaobject -> First Entry </term> +</inlinemediaobject> First Entry </term> <listitem> - <para ->Jump to first entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to first entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2023,13 +1073,9 @@ <imageobject> <imagedata fileref="bottom.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Last Entry </term> +</inlinemediaobject> Last Entry </term> <listitem> - <para ->Jump to last entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to last entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2038,13 +1084,9 @@ <imageobject> <imagedata fileref="prevfuzzyuntrans.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Previous fuzzy or untranslated </term> +</inlinemediaobject> Previous fuzzy or untranslated </term> <listitem> - <para ->Jump to previous fuzzy or untranslated entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to previous fuzzy or untranslated entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2053,13 +1095,9 @@ <imageobject> <imagedata fileref="nextfuzzyuntrans.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Next fuzzy or untranslated </term> +</inlinemediaobject> Next fuzzy or untranslated </term> <listitem> - <para ->Jump to next fuzzy or untranslated entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to next fuzzy or untranslated entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2068,13 +1106,9 @@ <imageobject> <imagedata fileref="prevfuzzy.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Previous fuzzy </term> +</inlinemediaobject> Previous fuzzy </term> <listitem> - <para ->Jump to previous fuzzy entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to previous fuzzy entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2083,13 +1117,9 @@ <imageobject> <imagedata fileref="nextfuzzy.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Next fuzzy </term> +</inlinemediaobject> Next fuzzy </term> <listitem> - <para ->Jump to next fuzzy entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to next fuzzy entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2098,13 +1128,9 @@ <imageobject> <imagedata fileref="prevuntranslated.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Previous untranslated </term> +</inlinemediaobject> Previous untranslated </term> <listitem> - <para ->Jump to previous untranslated entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to previous untranslated entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2113,13 +1139,9 @@ <imageobject> <imagedata fileref="nextuntranslated.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Next untranslated </term> +</inlinemediaobject> Next untranslated </term> <listitem> - <para ->Jump to next untranslated entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to next untranslated entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2128,13 +1150,9 @@ <imageobject> <imagedata fileref="preverror.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Previous error </term> +</inlinemediaobject> Previous error </term> <listitem> - <para ->Jump to previous error in <acronym ->PO</acronym -> file.</para> + <para>Jump to previous error in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2143,13 +1161,9 @@ <imageobject> <imagedata fileref="nexterror.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Next error </term> +</inlinemediaobject> Next error </term> <listitem> - <para ->Jump to next error in <acronym ->PO</acronym -> file.</para> + <para>Jump to next error in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2158,13 +1172,9 @@ <imageobject> <imagedata fileref="back.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Back </term> +</inlinemediaobject> Back </term> <listitem> - <para ->Jump to last visited entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to last visited entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> @@ -2173,80 +1183,57 @@ <imageobject> <imagedata fileref="forward.png" format="PNG"/> </imageobject> -</inlinemediaobject -> Forward </term> +</inlinemediaobject> Forward </term> <listitem> - <para ->Jump to previous visited entry in <acronym ->PO</acronym -> file.</para> + <para>Jump to previous visited entry in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> </variablelist> </sect2> <sect2 id="status-bar"> -<title ->Status Bar</title> +<title>Status Bar</title> <variablelist> <varlistentry> - <term ->Current</term> + <term>Current</term> <listitem> - <para ->Current message in edited <acronym ->PO</acronym -> file.</para> + <para>Current message in edited <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> - <term ->Total</term> + <term>Total</term> <listitem> - <para ->Total number of messages in <acronym ->PO</acronym -> file.</para> + <para>Total number of messages in <acronym>PO</acronym> file.</para> </listitem> </varlistentry> <varlistentry> - <term ->Fuzzy</term> + <term>Fuzzy</term> <listitem> - <para ->Number of messages marked as fuzzy. They should be revised and translated if needed.</para> + <para>Number of messages marked as fuzzy. They should be revised and translated if needed.</para> </listitem> </varlistentry> <varlistentry> - <term ->Untranslated</term> + <term>Untranslated</term> <listitem> - <para ->Number of yet untranslated messages.</para> + <para>Number of yet untranslated messages.</para> </listitem> </varlistentry> <varlistentry> - <term ->Editor status</term> + <term>Editor status</term> <listitem> - <para ->INS - insert, and OVR - overwrite. Same meaning like in every ordinary text editor. </para> + <para>INS - insert, and OVR - overwrite. Same meaning like in every ordinary text editor. </para> </listitem> </varlistentry> <varlistentry> - <term ->PO-file status</term> + <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> + <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> + <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> + <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> @@ -2255,32 +1242,18 @@ </sect1> <sect1 id="catalogmanager-menu"> -<title ->The &catalogmanager; menu</title> +<title>The &catalogmanager; menu</title> <sect2> -<title ->The File Menu</title> +<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> + <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> + <action>Quits &catalogmanager;</action> </para> </listitem> </varlistentry> @@ -2288,142 +1261,75 @@ </sect2> <sect2> -<title ->The Edit Menu</title> +<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> + <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 dialogue for searching for strings in a set of PO files. </action> + <action>Open Find dialogue 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> + <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 dialogue for searching for and replacing strings in a set of PO files. </action> + <action>Open Replace dialogue 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> + <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> + <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> + <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> + <action>Toggle mark for the selected file. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Edit</guimenu -> <guimenuitem ->Remove Marking</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Remove Marking</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Removes mark for the selected file or folder. </action> + <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> + <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Toggle All Markings</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Toggles marks for the selected file or folder (recursively). </action> + <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> + <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Remove All Markings</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Remove marks for the selected file or folder (recursively). </action> + <action>Remove marks for the selected file or folder (recursively). </action> </para> </listitem> </varlistentry> @@ -2431,50 +1337,25 @@ </sect2> <sect2> -<title ->The Tools Menu</title> +<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> + <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> + <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> + <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> + <action>Check syntax for the selected file or subtree using msgfmt. </action> </para> </listitem> </varlistentry> @@ -2482,101 +1363,64 @@ </sect2> <sect2> -<title ->The Settings Menu</title> +<title>The Settings Menu</title> <variablelist> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Show Toolbar</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Show Toolbar</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->When checked, standard toolbar is displayed. </action> + <action>When checked, standard toolbar is displayed. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Show Statusbar</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Show Statusbar</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->When checked, bottom statusbar is displayed. </action> + <action>When checked, bottom statusbar is displayed. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Configure Key Bindings...</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Key Bindings...</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Opens a configure dialogue for binding keys to actions. This will let you to customise the default key bindings to suite your needs. </action> + <action>Opens a configure dialogue for binding keys to actions. This will let you to customise the default key bindings to suite your needs. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Configure Toolbars...</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Toolbars...</guimenuitem> </menuchoice> </term> <listitem> <para> - <action ->Standard toolbar-configuration dialogue will open. You can choose which actions will go in which toolbars and what toolbar to customise. </action> + <action>Standard toolbar-configuration dialogue will open. You can choose which actions will go in which toolbars and what toolbar to customise. </action> </para> </listitem> </varlistentry> <varlistentry> <term> - <menuchoice -><guimenu ->Settings</guimenu -> <guimenuitem ->Configure KBabel - Catalogue Manager...</guimenuitem -> </menuchoice> + <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure KBabel - Catalogue Manager...</guimenuitem> </menuchoice> </term> <listitem> - <para -><action -> All &catalogmanager; specific settings go here. </action -> Please read <link linkend="preferences-catalogmanager" ->Preferences</link -> section for specific topics. </para> + <para><action> All &catalogmanager; specific settings go here. </action> Please read <link linkend="preferences-catalogmanager">Preferences</link> section for specific topics. </para> </listitem> </varlistentry> </variablelist> </sect2> <sect2> -<title ->The Help Menu</title> +<title>The Help Menu</title> &help.menu.documentation; </sect2> -</sect1 -></chapter> +</sect1></chapter> <!-- Local Variables: mode: xml diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/preferences.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/preferences.docbook index 1e92e0dc2b1..8bf0f0594da 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/preferences.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/preferences.docbook @@ -1,6 +1,5 @@ <!-- <?xml version="1.0" ?> -<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" -> --> +<!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 --> @@ -11,95 +10,35 @@ <!-- Fill in this section if this document has a different author --> <authorgroup> <author> -<personname -><firstname -></firstname -><surname -></surname -></personname> +<personname><firstname></firstname><surname></surname></personname> </author> </authorgroup> -<othercredit role="translator" -><firstname ->Alex</firstname -><surname ->Walker</surname -><affiliation -><address -><email ->alex@x3ja.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Alex</firstname><surname>Walker</surname><affiliation><address><email>alex@x3ja.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </chapterinfo> -<title ->Preferences</title> +<title>Preferences</title> <sect1 id="preferences-kbabel"> -<title ->&kbabel; preferences</title> - -<para ->To show the Preferences dialogue 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> - -<para ->The left side of the preferences dialogue lists the categories of customisable 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> +<title>&kbabel; preferences</title> + +<para>To show the Preferences dialogue 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> + +<para>The left side of the preferences dialogue lists the categories of customisable 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> <sect2 id="preferences-identity"> -<title ->Identity</title> - -<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-save" ->Save</link -> section of the Preferences dialogue.</para> - -<warning -><para ->Character sequences for timezones are not standardised. So you should not use the string set here in time specification for saving in <link linkend="preferences-save" ->Save</link -> tab. You should use <literal ->%z</literal -> instead.</para -></warning> +<title>Identity</title> + +<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-save">Save</link> section of the Preferences dialogue.</para> + +<warning><para>Character sequences for timezones are not standardised. So you should not use the string set here in time specification for saving in <link linkend="preferences-save">Save</link> tab. You should use <literal>%z</literal> instead.</para></warning> <variablelist> <varlistentry> -<term -><guilabel ->Number of singular/plural forms</guilabel -></term> +<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 gettext plural forms.</para -></note -> +<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 gettext plural forms.</para></note> </listitem> </varlistentry> </variablelist> @@ -107,148 +46,61 @@ </sect2> <sect2 id="preferences-editor"> -<title ->Editor</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> +<title>Editor</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> - -<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> +<title>General</title> + +<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> + <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> + <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> + <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 the accelerator marker is & (but not in every programming toolkit). See the <link linkend="preferences-miscellaneous" ->Miscellaneous</link -> section below to find how to change a keyboard accelerator.</para> +<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 the accelerator marker is & (but not in every programming toolkit). See the <link linkend="preferences-miscellaneous">Miscellaneous</link> section below to find how to change a keyboard accelerator.</para> </listitem> </varlistentry> <varlistentry> - <term -><guilabel ->Check Equation</guilabel -></term> + <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 <acronym ->PO</acronym ->-files. </para> + <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 <acronym>PO</acronym>-files. </para> </listitem> </varlistentry> <varlistentry> - <term -><guilabel ->Look for Translated Context Info</guilabel -></term> + <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> +<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> + <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-identity" -><guilabel ->Identity</guilabel -></link -> tab. Incorrect number of plural forms can result in crash of an application. </para> + <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-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> + <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> + <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 colour on error</guilabel -></term> + <term><guilabel>Change text colour 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 colour on errors. </para> + <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 colour on errors. </para> </listitem> </varlistentry> </variablelist> @@ -256,724 +108,302 @@ </sect3> <sect3 id="preferences-editor-appearance"> -<title ->Appearance</title> +<title>Appearance</title> -<para ->These options let you configure the appearance for the message editor. In upper part there are 4 checkboxes: </para> +<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> + <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> + <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> + <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> + <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 colour choices to make editing easy. Colours can be changed by clicking on colour-picker buttons. From the 'select color' dialogs you can choose from standard colours, custom colours or just pick a colour from any part of your screen. </para> +<para>For the different items in edited text there are different colour choices to make editing easy. Colours can be changed by clicking on colour-picker buttons. From the 'select color' dialogs you can choose from standard colours, custom colours or just pick a colour from any part of your screen. </para> <variablelist> <varlistentry> - <term -><guilabel ->Background colour</guilabel -></term> - <listitem -><para ->This sets the background colour for characters in the MsgID view and the MsgStr editor. To change the general background colour of edit boxes you must use the &kcontrolcenter;. </para -></listitem> + <term><guilabel>Background colour</guilabel></term> + <listitem><para>This sets the background colour for characters in the MsgID view and the MsgStr editor. To change the general background colour of edit boxes you must use the &kcontrolcenter;. </para></listitem> </varlistentry> <varlistentry> - <term -><guilabel ->Colour for quoted characters</guilabel -></term> - <listitem -><para ->Here you can adjust the colour for escaped characters like (<literal ->\"</literal ->) double quotes or (<literal ->\n</literal ->) newline. </para -></listitem> + <term><guilabel>Colour for quoted characters</guilabel></term> + <listitem><para>Here you can adjust the colour for escaped characters like (<literal>\"</literal>) double quotes or (<literal>\n</literal>) newline. </para></listitem> </varlistentry> <varlistentry> - <term -><guilabel ->Colour for syntax errors</guilabel -></term> - <listitem -><para ->This is the colour 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> + <term><guilabel>Colour for syntax errors</guilabel></term> + <listitem><para>This is the colour 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 ->Colour for c-format characters</guilabel -></term> - <listitem -><para ->This sets the colour 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> + <term><guilabel>Colour for c-format characters</guilabel></term> + <listitem><para>This sets the colour 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 ->Colour 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-miscellaneous" ->Miscellaneous</link -> section below to find how to change keyboard accelerator. </para -></listitem> + <term><guilabel>Colour 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-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 colours 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 colour button chooser. </para> +<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 colours 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 colour button chooser. </para> </sect3> <sect3 id="preferences-editor-fonts"> -<title ->Fonts</title> +<title>Fonts</title> -<para ->This is a standard &kde; font chooser dialogue 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 dialogue lets you set font family, style, size and encoding. The bottom box shows a preview of the current font for user convenience. </para> +<para>This is a standard &kde; font chooser dialogue 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 dialogue lets you set font family, style, size and encoding. The bottom box shows a preview of the current font for user convenience. </para> </sect3> </sect2> <sect2 id="preferences-save"> -<title ->Save</title> -<para ->This section allows you to edit the options for <acronym ->PO</acronym -> file saving. The first group of checkboxes controls general behaviour for actions performed in <acronym ->PO</acronym -> file saving. </para> +<title>Save</title> +<para>This section allows you to edit the options for <acronym>PO</acronym> file saving. The first group of checkboxes controls general behaviour 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> + <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're doing. </para -></listitem> + <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're doing. </para></listitem> </varlistentry> </variablelist> -<para ->If you don't 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 from bellow formats:</para> +<para>If you don't 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 from bellow formats:</para> <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> + <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> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> </row> </thead> <tbody> <row> - <entry ->%y</entry -><entry ->year</entry -><entry ->00 to 99</entry> + <entry>%y</entry><entry>year</entry><entry>00 to 99</entry> </row> <row> - <entry ->%Y</entry -><entry ->year</entry -><entry ->0001 to 9999</entry> + <entry>%Y</entry><entry>year</entry><entry>0001 to 9999</entry> </row> </tbody> </tgroup> </table> <table> - <title ->Month</title> + <title>Month</title> <tgroup cols="3"> <thead> <row> - <entry ->Format</entry -><entry ->Meaning</entry -><entry ->Range</entry> + <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> + <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> + <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> + <entry>%b,%h</entry><entry>month abbreviation</entry><entry>Jan to Dec</entry> </row> </tbody> </tgroup> </table> <table> - <title ->Day</title> + <title>Day</title> <tgroup cols="3"> <thead> <row> - <entry ->Format</entry -><entry ->Meaning</entry -><entry ->Range</entry> + <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> + <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> + <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> + <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> + <entry>%a</entry><entry>weekday abbreviation</entry><entry>Sun to Sat</entry> </row> </tbody> </tgroup> </table> <table> - <title ->Hour</title> + <title>Hour</title> <tgroup cols="3"> <thead> <row> - <entry ->Format</entry -><entry ->Meaning</entry -><entry ->Range</entry> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> </row> </thead> <tbody> <row> - <entry ->%H</entry -><entry ->hour</entry -><entry ->00 to 23</entry> + <entry>%H</entry><entry>hour</entry><entry>00 to 23</entry> </row> <row> - <entry ->%k</entry -><entry ->hour</entry -><entry ->0 to 23</entry> + <entry>%k</entry><entry>hour</entry><entry>0 to 23</entry> </row> <row> - <entry ->%i</entry -><entry ->hour</entry -><entry ->1 to 12</entry> + <entry>%i</entry><entry>hour</entry><entry>1 to 12</entry> </row> <row> - <entry ->%I</entry -><entry ->hour</entry -><entry ->01 to 12</entry> + <entry>%I</entry><entry>hour</entry><entry>01 to 12</entry> </row> <row> - <entry ->%p</entry -><entry -></entry -><entry ->AM or PM</entry> + <entry>%p</entry><entry></entry><entry>AM or PM</entry> </row> </tbody> </tgroup> </table> <table> - <title ->Minute, Second, Timezone</title> + <title>Minute, Second, Timezone</title> <tgroup cols="3"> <thead> <row> - <entry ->Format</entry -><entry ->Meaning</entry -><entry ->Range</entry> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> </row> </thead> <tbody> <row> - <entry ->%M</entry -><entry ->minute</entry -><entry ->00 to 59</entry> + <entry>%M</entry><entry>minute</entry><entry>00 to 59</entry> </row> <row> - <entry ->%S</entry -><entry ->second</entry -><entry ->00 to 59</entry> + <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> + <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> + <entry>%z</entry><entry>timezone</entry><entry>(numeric offset as specified by system settings)</entry> </row> </tbody> </tgroup> </table> - </para -></listitem> + </para></listitem> </itemizedlist> -<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 <filename ->desktop.po</filename -> file <emphasis ->must</emphasis -> be UTF-8 encoded. The drop-down list lets you select message encoding. You must at least have your language code and UTF-8 encoding set. If, for some reason, you don't want to accidentally change the current PO file encoding, turn on <guibutton ->Keep the encoding of the file</guibutton ->.</para> +<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 <filename>desktop.po</filename> file <emphasis>must</emphasis> be UTF-8 encoded. The drop-down list lets you select message encoding. You must at least have your language code and UTF-8 encoding set. If, for some reason, you don't want to accidentally change the current PO file encoding, turn on <guibutton>Keep the encoding of the file</guibutton>.</para> </sect2> <sect2 id="preferences-spellcheck"> -<title ->Spell Check</title> +<title>Spell Check</title> -<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> +<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> + <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> + <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> + <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:/tdespell" ->tdespell</ulink -> documentation for more details. </para -></listitem> + <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:/tdespell">tdespell</ulink> documentation for more details. </para></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> + <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> + <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 ->$(HOME)/.trinity/share/apps/kbabel/spellignores</filename ->, where <filename ->$(HOME)</filename -> is your home folder. </para -></listitem> + <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>$(HOME)/.trinity/share/apps/kbabel/spellignores</filename>, where <filename>$(HOME)</filename> is your home folder. </para></listitem> </varlistentry> </variablelist> </sect2> <sect2 id="preferences-search"> -<title ->Search</title> -<para ->The search section allows you to customise various settings for searching in previously translated strings. </para> +<title>Search</title> +<para>The search section allows you to customise various settings for searching in previously translated strings. </para> <sect3 id="preferences-search-general"> -<title ->General</title> - -<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> +<title>General</title> + +<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> +<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> +<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> +<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> +<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> +<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> </sect3> </sect2> <sect2 id="preferences-diffmode"> -<title ->Diff</title> - -<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 colour, while <guilabel ->Underlined</guilabel ->(for added characters) or <guilabel ->Stroked Out</guilabel -> (for removed characters) will denote the changed parts by coloured 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> +<title>Diff</title> + +<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 colour, while <guilabel>Underlined</guilabel>(for added characters) or <guilabel>Stroked Out</guilabel> (for removed characters) will denote the changed parts by coloured 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-miscellaneous"> -<title ->Miscellaneous</title> -<para -><guilabel ->Miscellaneous</guilabel -> section holds settings which don't fit anywhere else. Currently there are two: </para> +<title>Miscellaneous</title> +<para><guilabel>Miscellaneous</guilabel> section holds settings which don't fit anywhere else. Currently there are two: </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> + <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> + <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> @@ -982,233 +412,61 @@ </sect1> <sect1 id="preferences-catalogmanager"> -<title ->&cataloguemanager; preferences</title> +<title>&cataloguemanager; preferences</title> -<para ->This dialogue allows you to edit the options for the Catalogue Manager. </para> +<para>This dialogue allows you to edit the options for the Catalogue Manager. </para> <sect2 id="preferences-catalogmanager-general"> -<title ->General</title> -<para ->Here are two edit lines with <guibutton ->Browse...</guibutton -> buttons. Type in the folders which 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 Catalogue Manager window. </para> - -<para ->Below you can turn on and off if: </para> +<title>General</title> +<para>Here are two edit lines with <guibutton>Browse...</guibutton> buttons. Type in the folders which 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 Catalogue 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 Catalogue Manager are opened in a new window. </para -></listitem> + <term><guibutton>Open files in new window</guibutton></term> + <listitem><para>If this is activated all files that are opened from the Catalogue 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> + <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> + <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-catalogmanager-folders"> -<title ->Folder Commands</title> -<para ->Here you can insert commands you want to execute in folders from the Catalogue Manager. The commands are then shown in the submenu <menuchoice -><guimenuitem ->Commands</guimenuitem -></menuchoice -> in the Catalogue Manager's context menu. </para -><para ->Insert in the <guilabel ->Name</guilabel -> field the name of the command. The name 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 Catalogue Manager. </para -><para ->The following strings will be replaced in a command: </para> +<title>Folder Commands</title> +<para>Here you can insert commands you want to execute in folders from the Catalogue Manager. The commands are then shown in the submenu <menuchoice><guimenuitem>Commands</guimenuitem></menuchoice> in the Catalogue Manager's context menu. </para><para>Insert in the <guilabel>Name</guilabel> field the name of the command. The name 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 Catalogue 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> + <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> +<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> -<title ->File Commands</title> -<para ->Here you can insert the commands you want to execute on files from the Catalogue Manager. The commands are then shown in the submenu <menuchoice -><guimenuitem ->Commands</guimenuitem -></menuchoice -> in the Catalogue Manager's context menu. </para> - -<para ->Insert in the <guilabel ->Name</guilabel -> field the name of the command. The name 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 Catalogue Manager, is. </para -><para ->The following strings will be replaced in a command: </para> +<title>File Commands</title> +<para>Here you can insert the commands you want to execute on files from the Catalogue Manager. The commands are then shown in the submenu <menuchoice><guimenuitem>Commands</guimenuitem></menuchoice> in the Catalogue Manager's context menu. </para> + +<para>Insert in the <guilabel>Name</guilabel> field the name of the command. The name 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 Catalogue 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> + <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> +<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> </sect1> </chapter> diff --git a/tde-i18n-en_GB/docs/tdesdk/kbabel/using.docbook b/tde-i18n-en_GB/docs/tdesdk/kbabel/using.docbook index 9741d7ba9a6..656e8052fa3 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbabel/using.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbabel/using.docbook @@ -1,6 +1,5 @@ <!-- <?xml version="1.0" ?> -<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" -> --> +<!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 --> @@ -10,413 +9,157 @@ <!-- Fill in this section if this document has a different author --> <authorgroup> <author> -<personname -><firstname -></firstname -><surname -></surname -></personname> +<personname><firstname></firstname><surname></surname></personname> </author> </authorgroup> -<othercredit role="translator" -><firstname ->Alex</firstname -><surname ->Walker</surname -><affiliation -><address -><email ->alex@x3ja.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Alex</firstname><surname>Walker</surname><affiliation><address><email>alex@x3ja.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </chapterinfo> -<title ->Using &kbabel;</title> +<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 favourite applications speak your native non-English language. This process of adapting an application to a specific language is known as localisation. The localisation 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 internationalisation process to make an application's interface speak many languages.</para> - -<para ->Every internationalisation-aware program makes available for translation one or more message-catalogue 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 ->Every translator takes a <acronym ->POT</acronym -> file copy and begins translating messages. This file will became a <acronym ->PO</acronym -> file - Portable Object and represents only one language.</para> - -<para ->Each translator takes a copy of one of these POT templates and begins filling 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, act as a database to minimise 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 catalogue can become corrupted and needs to be manually fixed. Most of these problems are the so-hated <acronym ->CVS</acronym -> conflicts which occur when a translating process is coordinated by a concurrent version system (see the <ulink url="info:/cvs" ->CVS</ulink -> documentation). &kbabel; can't help you very 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> - -<para ->Empty lines and those starting with <literal ->#</literal -> are ignored. Lines starting with a # represent comments and are a useful means 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 aide 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 ->Recent versions of <application ->&GNU; gettext</application -> added another useful i18n feature 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. 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. </para> -<para ->Plural forms in <acronym ->PO</acronym -> files are here to help. Unfortunately, &kde; developers do not like the plural forms implementation in <application ->&GNU; gettext</application -> and they have introduced their own format and handling for them. </para> +<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 favourite applications speak your native non-English language. This process of adapting an application to a specific language is known as localisation. The localisation 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 internationalisation process to make an application's interface speak many languages.</para> + +<para>Every internationalisation-aware program makes available for translation one or more message-catalogue 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>Every translator takes a <acronym>POT</acronym> file copy and begins translating messages. This file will became a <acronym>PO</acronym> file - Portable Object and represents only one language.</para> + +<para>Each translator takes a copy of one of these POT templates and begins filling 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, act as a database to minimise 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 catalogue can become corrupted and needs to be manually fixed. Most of these problems are the so-hated <acronym>CVS</acronym> conflicts which occur when a translating process is coordinated by a concurrent version system (see the <ulink url="info:/cvs">CVS</ulink> documentation). &kbabel; can't help you very 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> + +<para>Empty lines and those starting with <literal>#</literal> are ignored. Lines starting with a # represent comments and are a useful means 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 aide 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>Recent versions of <application>&GNU; gettext</application> added another useful i18n feature 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. 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. </para> +<para>Plural forms in <acronym>PO</acronym> files are here to help. Unfortunately, &kde; developers do not like the plural forms implementation in <application>&GNU; gettext</application> and they have introduced their own format and handling for them. </para> </sect1> <sect1 id="using-editor"> -<title ->Editor</title> +<title>Editor</title> -<para ->Here is a screenshot of &kbabel;. 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>Here is a screenshot of &kbabel;. 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>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>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>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> +<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> +<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> <screenshot> -<screeninfo ->Screenshot of &kbabel;</screeninfo> +<screeninfo>Screenshot of &kbabel;</screeninfo> <mediaobject> <imageobject> <imagedata fileref="snap1.png" format="PNG"/> </imageobject> -<textobject -><phrase ->Screenshot of &kbabel;</phrase -></textobject> +<textobject><phrase>Screenshot of &kbabel;</phrase></textobject> </mediaobject> </screenshot> -<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. Dialogue interface translation is a good example, or widgets with their associated text and "what's this" message. </para> +<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. Dialogue 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> +<title>More &kbabel; Features</title> -<para ->Each msgid entry can be in three states: </para> +<para>Each msgid entry can be in three states: </para> <variablelist> <varlistentry> - <term ->untranslated</term> + <term>untranslated</term> <listitem> - <para ->there is no translated text currently associated with the msgstr </para> + <para>there is no translated text currently associated with the msgstr </para> </listitem> </varlistentry> <varlistentry> - <term ->fuzzy</term> + <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> + <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> + <term>translated</term> <listitem> - <para ->the msgid is the completed translated form of the msgstr </para> + <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 customisable colour (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> +<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 customisable colour (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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> @@ -424,138 +167,47 @@ </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 summarises clever editing features. </para> +<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 summarises 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> +<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> +<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> +<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> +<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 are spaces, you can turn on <guibutton ->Highlight background</guibutton -> and/or <guibutton ->Mark whitespaces with points</guibutton -> in preferences dialogue on tab <guilabel ->Edit</guilabel -> <guilabel ->Appearance</guilabel ->. </para> +<para>If you want to see where are spaces, you can turn on <guibutton>Highlight background</guibutton> and/or <guibutton>Mark whitespaces with points</guibutton> in preferences dialogue 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 dialogue: </para> +<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 dialogue: </para> <para> <screenshot> -<screeninfo ->Rough translation dialogue</screeninfo> +<screeninfo>Rough translation dialogue</screeninfo> <mediaobject> <imageobject> <imagedata fileref="roughtranslation.png" format="PNG"/> @@ -563,298 +215,122 @@ </mediaobject> </screenshot> </para> -<para ->In the dialogue, 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> +<para>In the dialogue, 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 dialogue</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> +<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 dialogue</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> + <term><guimenuitem>Check Syntax</guimenuitem></term> <listitem> - <para ->This invokes <command ->msgfmt</command -> to check validity of the PO file as seen by gettext package. It will show the result of the command and mark error <acronym ->msgstr</acronym ->s. </para> + <para>This invokes <command>msgfmt</command> to check validity of the PO file as seen by 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> + <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> + <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> + <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> + <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> + <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> + <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> + <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 -> dialogue. This is implemented only for &kde; at the moment. </para> + <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> dialogue. This is implemented only for &kde; at the moment. </para> </listitem> </varlistentry> <varlistentry> - <term -><guimenuitem ->Check Equations</guimenuitem -></term> + <term><guimenuitem>Check Equations</guimenuitem></term> <listitem> - <para ->Equations are special format of <acronym ->msgid</acronym -> typically used in .desktop 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 ->. </para> + <para>Equations are special format of <acronym>msgid</acronym> typically used in .desktop 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>. </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-spellcheck" ->the &kbabel; configuration dialogue</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> +<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-spellcheck">the &kbabel; configuration dialogue</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> + <term><guimenuitem>Spell check...</guimenuitem></term> <listitem> - <para ->This is a generic invocation of a dialogue 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> + <para>This is a generic invocation of a dialogue 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> + <term><guimenuitem>Check All...</guimenuitem></term> <listitem> - <para ->Spellcheck all messages in the file. </para> + <para>Spellcheck all messages in the file. </para> </listitem> </varlistentry> <varlistentry> - <term -><guimenuitem ->Check from Cursor Position...</guimenuitem -></term> + <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> + <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> + <term><guimenuitem>Check Current...</guimenuitem></term> <listitem> - <para ->Spellcheck the current message only. </para> + <para>Spellcheck the current message only. </para> </listitem> </varlistentry> <varlistentry> - <term -><guimenuitem ->Check Selected Text...</guimenuitem -></term> + <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> + <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> +<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> +<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> +<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> + <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> + <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> + <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> + <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> @@ -862,142 +338,50 @@ </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 dialogue</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 dialogue</link ->: </para> +<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 dialogue</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 dialogue</link>: </para> <variablelist> <varlistentry> - <term ->Translation Database</term> + <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 dialogue</link ->. This mode can be turned on by <guilabel ->Use messages from Translation Database</guilabel ->. </para> + <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 dialogue</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> + <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> + <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> + <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> + <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> +<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 suport in &kbabel;. </para> -<para ->&kbabel; can read the &GNU; plural forms only, but cannot edit them. It only supports the &kde; version of plural forms at the moment. </para> -<para ->Every language to which &kde; is translated must have set a correct number of plural forms. This is done by translating an entry in <filename ->tdelibs.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 tdelibs source code, in the file <filename ->tdecore/tdelocale.cpp</filename ->. </para> -<para ->&kde; plural forms are denoted by comment <userinput ->_:</userinput -> 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 ->. For example, <quote ->Selected %n files</quote -> translated to Slovak would be: </para> -<programlisting ->Vybraný %n súbor\n +<title>Plural Forms</title> +<para>Because plural forms are quite a complicated issue, we devote a special section for their suport in &kbabel;. </para> +<para>&kbabel; can read the &GNU; plural forms only, but cannot edit them. It only supports the &kde; version of plural forms at the moment. </para> +<para>Every language to which &kde; is translated must have set a correct number of plural forms. This is done by translating an entry in <filename>tdelibs.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 tdelibs source code, in the file <filename>tdecore/tdelocale.cpp</filename>. </para> +<para>&kde; plural forms are denoted by comment <userinput>_:</userinput> 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>. For example, <quote>Selected %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> +<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> diff --git a/tde-i18n-en_GB/docs/tdesdk/kbugbuster/index.docbook b/tde-i18n-en_GB/docs/tdesdk/kbugbuster/index.docbook index 1b59451fa02..937becd8f11 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kbugbuster/index.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kbugbuster/index.docbook @@ -9,43 +9,16 @@ <book lang="&language;"> <bookinfo> -<title ->The &kbugbuster; Handbook</title> +<title>The &kbugbuster; Handbook</title> <authorgroup> -<author -><firstname -></firstname -> <othername -></othername -> <surname -></surname -> <affiliation -> <address -><email -></email -></address> +<author><firstname></firstname> <othername></othername> <surname></surname> <affiliation> <address><email></email></address> </affiliation> </author> -<othercredit role="translator" -><firstname ->Malcolm</firstname -><surname ->Hunter</surname -><affiliation -><address -><email ->malcolm.hunter@gmx.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Malcolm</firstname><surname>Hunter</surname><affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </authorgroup> -<legalnotice ->&FDLNotice;</legalnotice> +<legalnotice>&FDLNotice;</legalnotice> <!-- Date and version information of the documentation Don't forget to include this last date and this last revision number, we @@ -53,44 +26,24 @@ 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> +<date>2002-03-31</date> +<releaseinfo>0.00.00</releaseinfo> <!-- Abstract about this handbook --> <abstract> -<para ->&kbugbuster; is part of the tdesdk package. </para> +<para>&kbugbuster; is part of the tdesdk package. </para> </abstract> <keywordset> -<keyword ->KDE</keyword> -<keyword ->kbugbuster</keyword> +<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-user@kde.org" ->The &kde; User Mailing list</ulink ->.</para -> <para -><emphasis ->The &kde; Team</emphasis -></para -> &underFDL; </chapter> +<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-user@kde.org">The &kde; User Mailing list</ulink>.</para> <para><emphasis>The &kde; Team</emphasis></para> &underFDL; </chapter> &documentation.index; </book> diff --git a/tde-i18n-en_GB/docs/tdesdk/kompare/index.docbook b/tde-i18n-en_GB/docs/tdesdk/kompare/index.docbook index b44f14de61f..c8845c138a5 100644 --- a/tde-i18n-en_GB/docs/tdesdk/kompare/index.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/kompare/index.docbook @@ -9,43 +9,16 @@ <book lang="&language;"> <bookinfo> -<title ->The &kompare; Handbook</title> +<title>The &kompare; Handbook</title> <authorgroup> -<author -><firstname -></firstname -> <othername -></othername -> <surname -></surname -> <affiliation -> <address -><email -></email -></address> +<author><firstname></firstname> <othername></othername> <surname></surname> <affiliation> <address><email></email></address> </affiliation> </author> -<othercredit role="translator" -><firstname ->Malcolm</firstname -><surname ->Hunter</surname -><affiliation -><address -><email ->malcolm.hunter@gmx.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Malcolm</firstname><surname>Hunter</surname><affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </authorgroup> -<legalnotice ->&FDLNotice;</legalnotice> +<legalnotice>&FDLNotice;</legalnotice> <!-- Date and version information of the documentation Don't forget to include this last date and this last revision number, we @@ -53,44 +26,24 @@ 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-12-16</date> -<releaseinfo ->0.00.00</releaseinfo> +<date>2002-12-16</date> +<releaseinfo>0.00.00</releaseinfo> <!-- Abstract about this handbook --> <abstract> -<para ->&kompare; is a program to view the differences between files. </para> +<para>&kompare; is a program to view the differences between files. </para> </abstract> <keywordset> -<keyword ->KDE</keyword> -<keyword ->Kompare</keyword> +<keyword>KDE</keyword> +<keyword>Kompare</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-user@kde.org" ->The &kde; User Mailing list</ulink ->.</para -> <para -><emphasis ->The &kde; Team</emphasis -></para -> &underFDL; </chapter> +<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-user@kde.org">The &kde; User Mailing list</ulink>.</para> <para><emphasis>The &kde; Team</emphasis></para> &underFDL; </chapter> &documentation.index; </book> diff --git a/tde-i18n-en_GB/docs/tdesdk/tdecachegrind/index.docbook b/tde-i18n-en_GB/docs/tdesdk/tdecachegrind/index.docbook index 443be3d40cd..10f44686ac9 100644 --- a/tde-i18n-en_GB/docs/tdesdk/tdecachegrind/index.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/tdecachegrind/index.docbook @@ -1,23 +1,11 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ - <!ENTITY tdecachegrind '<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 tdecachegrind '<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 "&tdecachegrind;"> <!ENTITY package "tdesdk"> <!ENTITY % addindex "IGNORE"> @@ -29,167 +17,96 @@ <book lang="&language;"> <bookinfo> -<title ->The &tdecachegrind; Handbook</title> +<title>The &tdecachegrind; Handbook</title> <authorgroup> -<author -><firstname ->Josef</firstname -> <surname ->Weidendorfer</surname -> <affiliation -> <address -><email ->Josef.Weidendorfer@gmx.de</email -></address> +<author><firstname>Josef</firstname> <surname>Weidendorfer</surname> <affiliation> <address><email>Josef.Weidendorfer@gmx.de</email></address> </affiliation> </author> -<othercredit role="translator" -><firstname ->Andrew</firstname -><surname ->Coles</surname -><affiliation -><address -><email ->andrew_coles@yahoo.co.uk</email -></address -></affiliation -><contrib ->Conversion to British English</contrib -></othercredit -> +<othercredit role="translator"><firstname>Andrew</firstname><surname>Coles</surname><affiliation><address><email>andrew_coles@yahoo.co.uk</email></address></affiliation><contrib>Conversion to British English</contrib></othercredit> </authorgroup> <copyright> -<year ->2002-2004</year> -<holder ->Josef Weidendorfer</holder> +<year>2002-2004</year> +<holder>Josef Weidendorfer</holder> </copyright> -<legalnotice ->&FDLNotice;</legalnotice> +<legalnotice>&FDLNotice;</legalnotice> -<date ->2004-07-27</date> -<releaseinfo ->0.4.6</releaseinfo> +<date>2004-07-27</date> +<releaseinfo>0.4.6</releaseinfo> <abstract> -<para ->&tdecachegrind; is a profile data visualisation tool, written using the &kde; environment. </para> +<para>&tdecachegrind; is a profile data visualisation tool, written using the &kde; environment. </para> </abstract> <keywordset> -<keyword ->KDE</keyword> -<keyword ->tdesdk</keyword> -<keyword ->Cachegrind</keyword> -<keyword ->Callgrind</keyword> -<keyword ->Valgrind</keyword> -<keyword ->Profiling</keyword> +<keyword>KDE</keyword> +<keyword>tdesdk</keyword> +<keyword>Cachegrind</keyword> +<keyword>Callgrind</keyword> +<keyword>Valgrind</keyword> +<keyword>Profiling</keyword> </keywordset> </bookinfo> <chapter id="introduction"> -<title ->Introduction</title> +<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> +<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> +<title>Profiling</title> -<para ->When developing a program, one of the last steps often involves performance optimisations. As it makes no sense to optimise 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>When developing a program, one of the last steps often involves performance optimisations. As it makes no sense to optimise 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 visualise this kind of data. </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 visualise this kind of data. </para> -<para ->After analysing 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 optimised. Afterwards, the success of the optimisation should be verified with another profile run. </para> +<para>After analysing 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 optimised. Afterwards, the success of the optimisation should be verified with another profile run. </para> </sect1> <sect1 id="introduction-methods"> -<title ->Profiling Methods</title> +<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>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 reinitialised 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>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 reinitialised 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 practise. 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> +<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 practise. 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> +<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 ->Visualisation</title> +<title>Visualisation</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>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 visualisation 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>&kappname; is an visualisation 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 visualisation 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> +<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 visualisation 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 visualised, together with inclusive cost metric for fast visual detection of problematic functions,</para> +<listitem><para>a tree-map view, which allows nested-call relations to be visualised, 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><para>source code and disassembler annotation views, allowing to see details of cost related to source lines and assembler instructions.</para> </listitem> </itemizedlist> @@ -198,409 +115,193 @@ </chapter> <chapter id="using-tdecachegrind"> -<title ->Using &tdecachegrind;</title> +<title>Using &tdecachegrind;</title> <sect1 id="using-profile"> -<title ->Generate Data to Visualise</title> +<title>Generate Data to Visualise</title> -<para ->First, one wants to generate performance data by measuring aspects of the runtime characteristics of an application, using a profiling tool. &tdecachegrind; 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 visualise 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> +<para>First, one wants to generate performance data by measuring aspects of the runtime characteristics of an application, using a profiling tool. &tdecachegrind; 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 visualise 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://tdecachegrind.sf.net" -> http://tdecachegrind.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 &tdecachegrind;. </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 &tdecachegrind;, all others are loaded too, and can be seen in the Parts Overview and Parts list. </para> +<title>&callgrind;</title> + +<para>&callgrind; is available from <ulink url="http://tdecachegrind.sf.net"> http://tdecachegrind.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 &tdecachegrind;. </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 &tdecachegrind;, 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 visualise the data in &tdecachegrind;, 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 &tdecachegrind; on its own. </para> +<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 visualise the data in &tdecachegrind;, 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 &tdecachegrind; on its own. </para> </sect2> </sect1> <sect1 id="using-basics"> -<title ->User Interface Basics</title> - -<para ->When starting &tdecachegrind; 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 visualisations for a selected function. This visualisation area can be arbitrarily configured to show multiple visualisations at once. </para> - -<para ->At first start, this area will be divided into a top and a bottom part, each with different visualisations selectable by tabs. To move visualisation views, use the context menu of the tabs, and adjust the splitters between visualisations. To quickly switch between different visualisation 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 visualisation: 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 visualisation; 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://tdecachegrind.sf.net" -> http://tdecachegrind.sf.net</ulink ->. Also, every widget in &tdecachegrind; has <quote ->What's this</quote -> help. </para> +<title>User Interface Basics</title> + +<para>When starting &tdecachegrind; 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 visualisations for a selected function. This visualisation area can be arbitrarily configured to show multiple visualisations at once. </para> + +<para>At first start, this area will be divided into a top and a bottom part, each with different visualisations selectable by tabs. To move visualisation views, use the context menu of the tabs, and adjust the splitters between visualisations. To quickly switch between different visualisation 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 visualisation: 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 visualisation; 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://tdecachegrind.sf.net"> http://tdecachegrind.sf.net</ulink>. Also, every widget in &tdecachegrind; has <quote>What's this</quote> help. </para> </sect1> </chapter> <chapter id="tdecachegrind-concepts"> -<title ->Basic Concepts</title> +<title>Basic Concepts</title> -<para ->This chapter explains some concepts of the &tdecachegrind;, and introduces terms used in the interface. </para> +<para>This chapter explains some concepts of the &tdecachegrind;, and introduces terms used in the interface. </para> <sect1 id="concepts-model"> -<title ->The Data Model for Profile Data</title> +<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> +<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> +<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 formulae for event types calculated from real events, which are called inherited events. </para> +<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 formulae for event types calculated from real events, which are called inherited events. </para> </sect2> </sect1> <sect1 id="concepts-state"> -<title ->Visualisation State</title> - -<para ->The Visualisation 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 colouring), </para -></listitem -> <listitem -><para -> the profile parts whose costs are to be included in visualisation, </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 visualisations. </para> -<para ->Visualisations always are shown for one, the active, cost entity. When a given visualisation 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> +<title>Visualisation State</title> + +<para>The Visualisation 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 colouring), </para></listitem> <listitem><para> the profile parts whose costs are to be included in visualisation, </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 visualisations. </para> +<para>Visualisations always are shown for one, the active, cost entity. When a given visualisation 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> +<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> +<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 ->Visualisation Area</title> -<para ->The visualisation 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 visualisation 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> +<title>Visualisation Area</title> +<para>The visualisation 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 visualisation 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 visualisation 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 visualisation should go into which area by using the context menus of the tabs. </para> +<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 visualisation 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 visualisation should go into which area by using the context menus of the tabs. </para> </sect2> <sect2> -<title ->Synchronised Visualisation via Selected Entity in a Tab View</title> -<para ->Besides an active entity, each tab view has an selected entity. As most visualisation types show multiple entities with the active one somehow centred, you can change the selected item by navigating inside a visualisation (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 visualisations of a tab view, all other visualisations in the tab view accordingly highlight the new selected entity. </para> +<title>Synchronised Visualisation via Selected Entity in a Tab View</title> +<para>Besides an active entity, each tab view has an selected entity. As most visualisation types show multiple entities with the active one somehow centred, you can change the selected item by navigating inside a visualisation (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 visualisations of a tab view, all other visualisations in the tab view accordingly highlight the new selected entity. </para> </sect2> <sect2> -<title ->Synchronisation 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> +<title>Synchronisation 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 visualisation 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> +<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 visualisation 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> +<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> +<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 coloured 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> +<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 coloured 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> +<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 ->Visualisations</title> +<title>Visualisations</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> +<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> +<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 visualisation of the primary event type, up or down the call hierarchy. Each coloured 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> +<title>Maps</title> +<para>A treemap visualisation of the primary event type, up or down the call hierarchy. Each coloured 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 visualisation options as for the Call Treemap; the selected function is highlighted. </para> +<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 visualisation 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> +<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> @@ -608,128 +309,42 @@ <chapter id="commands"> -<title ->Command Reference</title> +<title>Command Reference</title> <sect1 id="tdecachegrind-mainwindow"> -<title ->The main &tdecachegrind; window</title> -<para -></para> +<title>The main &tdecachegrind; window</title> +<para></para> <sect2> -<title ->The <guimenu ->File</guimenu -> Menu</title> +<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> +<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 Dialogue 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> +<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 Dialogue 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> +<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> +<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> +<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> @@ -737,96 +352,33 @@ </sect2> <sect2> -<title ->The <guimenu ->View</guimenu -> Menu</title> +<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> +<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> +<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> +<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> +<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> +<term><menuchoice><guimenu>View</guimenu> <guimenuitem>Split</guimenuitem> </menuchoice></term> +<listitem><para><action>(To-do)</action></para></listitem> </varlistentry> </variablelist> @@ -839,56 +391,44 @@ </chapter> <chapter id="faq"> -<title ->Questions and Answers</title> +<title>Questions and Answers</title> &reporting.bugs; &updating.documentation; <qandaset id="faqlist"> <qandaentry> <question> -<para ->What is &tdecachegrind; for? I have no idea. </para> +<para>What is &tdecachegrind; for? I have no idea. </para> </question> <answer> -<para ->&tdecachegrind; is a helpful at a later stage in software development, called Profiling. If you don't develop applications, you don't need &tdecachegrind;. </para> +<para>&tdecachegrind; is a helpful at a later stage in software development, called Profiling. If you don't develop applications, you don't need &tdecachegrind;. </para> </answer> </qandaentry> <qandaentry> <question> -<para ->What is the difference between 'Incl.' and 'Self' ? </para> +<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> +<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> +<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 TDEDIR to this directory before running KCachegrind. </para> +<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 TDEDIR 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> +<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> +<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> @@ -897,59 +437,21 @@ </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 visualisation 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> +<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 visualisation 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> @@ -957,52 +459,36 @@ <chapter id="credits"> -<title ->Credits and License</title> +<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> +<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; </chapter> <appendix id="installation"> -<title ->Installation</title> +<title>Installation</title> <sect1 id="getting-tdecachegrind"> -<title ->How to obtain &tdecachegrind;</title> +<title>How to obtain &tdecachegrind;</title> -<para ->&tdecachegrind; is part of the &package; package of &kde;. For less supported interim releases, &callgrind; and further documentation, see the homepage at <ulink url="http://tdecachegrind.sf.net" -> http://tdecachegrind.sf.net</ulink ->. Look there for further installation and compile instructions. </para> +<para>&tdecachegrind; is part of the &package; package of &kde;. For less supported interim releases, &callgrind; and further documentation, see the homepage at <ulink url="http://tdecachegrind.sf.net"> http://tdecachegrind.sf.net</ulink>. Look there for further installation and compile instructions. </para> </sect1> <sect1 id="requirements"> -<title ->Requirements</title> +<title>Requirements</title> -<para ->In order to successfully use &tdecachegrind;, you need &kde; 3.x. For generating profile data, &cachegrind; or &calltree;/&callgrind; is recommend. </para> +<para>In order to successfully use &tdecachegrind;, 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> +<title>Compilation and Installation</title> &install.compile.documentation; </sect1> <sect1 id="configuration"> -<title ->Configuration</title> +<title>Configuration</title> -<para ->All configuration options are either in the configuration dialogue or in the context popup menus of the visualisations. </para> +<para>All configuration options are either in the configuration dialogue or in the context popup menus of the visualisations. </para> </sect1> diff --git a/tde-i18n-en_GB/docs/tdesdk/umbrello/authors.docbook b/tde-i18n-en_GB/docs/tdesdk/umbrello/authors.docbook index 8978a5ae7c3..0d60d3f1396 100644 --- a/tde-i18n-en_GB/docs/tdesdk/umbrello/authors.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/umbrello/authors.docbook @@ -1,46 +1,15 @@ <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> +<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> +<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> +<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/tde-i18n-en_GB/docs/tdesdk/umbrello/code_import_and_generation.docbook b/tde-i18n-en_GB/docs/tdesdk/umbrello/code_import_and_generation.docbook index 429217884c1..ecb0b0354c7 100644 --- a/tde-i18n-en_GB/docs/tdesdk/umbrello/code_import_and_generation.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/umbrello/code_import_and_generation.docbook @@ -1,163 +1,82 @@ <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> +<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> +<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 through 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> +<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 through 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> +<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> + <phrase>Options for the Code Generation in &umbrello;</phrase> </textobject> <caption> - <para ->Options for the Code Generation in &umbrello; </para> + <para>Options for the Code Generation in &umbrello; </para> </caption> </mediaobject> </screenshot> </para> <sect3 id="generation-options"> -<title ->Generation Options</title> +<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> +<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> +<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> +<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> +<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> +<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><!--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> +<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--> +</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 dialogue 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> +<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 dialogue 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> +<screeninfo>Code Import</screeninfo> <mediaobject> <imageobject> <imagedata fileref="code-import.png" format="PNG"/> </imageobject> <textobject> - <phrase ->Menu for importing source code in &umbrello;</phrase> + <phrase>Menu for importing source code in &umbrello;</phrase> </textobject> <caption> - <para ->Menu for importing source code in &umbrello; </para> + <para>Menu for importing source code in &umbrello; </para> </caption> </mediaobject> </screenshot> </para> </sect1> -</chapter -> <!--code-import-generation--> +</chapter> <!--code-import-generation--> diff --git a/tde-i18n-en_GB/docs/tdesdk/umbrello/credits.docbook b/tde-i18n-en_GB/docs/tdesdk/umbrello/credits.docbook index b8a1c5500d9..384ee552c52 100644 --- a/tde-i18n-en_GB/docs/tdesdk/umbrello/credits.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/umbrello/credits.docbook @@ -1,11 +1,6 @@ <chapter id="copyright"> -<title ->Copyright</title> +<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> +<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/tde-i18n-en_GB/docs/tdesdk/umbrello/index.docbook b/tde-i18n-en_GB/docs/tdesdk/umbrello/index.docbook index 055f079585c..117ec0d1d50 100644 --- a/tde-i18n-en_GB/docs/tdesdk/umbrello/index.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/umbrello/index.docbook @@ -1,14 +1,10 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ - <!ENTITY umbrello "<application ->Umbrello &UML; Modeller</application ->"> + <!ENTITY umbrello "<application>Umbrello &UML; Modeller</application>"> <!ENTITY kappname "&umbrello;"> <!ENTITY packagename "tdesdk"> - <!ENTITY UML "<acronym ->UML</acronym ->"> + <!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"> @@ -17,59 +13,43 @@ <!ENTITY authors-chapter SYSTEM "authors.docbook"> <!ENTITY credits-chapter SYSTEM "credits.docbook"> <!ENTITY % addindex "IGNORE"> - <!ENTITY % British-English "INCLUDE" -><!-- change language only here --> + <!ENTITY % British-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> +<title>&umbrello; Handbook</title> <authorgroup> -<corpauthor ->&umbrello; Authors</corpauthor> +<corpauthor>&umbrello; Authors</corpauthor> </authorgroup> <copyright> -<year ->2001</year> -<holder ->Paul Hensgen</holder> +<year>2001</year> +<holder>Paul Hensgen</holder> </copyright> <copyright> -<year ->2002, 2003</year> -<holder ->&umbrello; Authors</holder> +<year>2002, 2003</year> +<holder>&umbrello; Authors</holder> </copyright> -<date ->2003-10-15</date> -<releaseinfo ->1.2</releaseinfo> +<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> +<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> +<keyword>KDE</keyword> +<keyword>UML</keyword> +<keyword>modelling</keyword> +<keyword>diagrams</keyword> +<keyword>software development</keyword> +<keyword>development</keyword> </keywordset> </bookinfo> diff --git a/tde-i18n-en_GB/docs/tdesdk/umbrello/introduction.docbook b/tde-i18n-en_GB/docs/tdesdk/umbrello/introduction.docbook index 1869425cc45..08cede5dc86 100644 --- a/tde-i18n-en_GB/docs/tdesdk/umbrello/introduction.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/umbrello/introduction.docbook @@ -1,57 +1,19 @@ <chapter id="introduction"> -<title ->Introduction</title> +<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> +<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> +<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> +<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/tde-i18n-en_GB/docs/tdesdk/umbrello/other_features.docbook b/tde-i18n-en_GB/docs/tdesdk/umbrello/other_features.docbook index 20fcfd9f765..ffdb636fd49 100644 --- a/tde-i18n-en_GB/docs/tdesdk/umbrello/other_features.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/umbrello/other_features.docbook @@ -1,72 +1,35 @@ <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> +<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> +<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> +<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 dialogue from where you can print your diagrams. </para> +<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 dialogue from where you can print your diagrams. </para> </sect2> <sect2 id="logical-folders"> -<title ->Logical Folders</title> -<para ->To better organise 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> +<title>Logical Folders</title> +<para>To better organise 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 ->Organising your Model with Folders</screeninfo> +<screeninfo>Organising your Model with Folders</screeninfo> <mediaobject> <imageobject> <imagedata fileref="folders.png" format="PNG"/> </imageobject> <textobject> - <phrase ->Organising a Model with Logical Folders in &umbrello;</phrase> + <phrase>Organising a Model with Logical Folders in &umbrello;</phrase> </textobject> <caption> - <para ->Organising a Model with Logical Folders in &umbrello; </para> + <para>Organising a Model with Logical Folders in &umbrello; </para> </caption> </mediaobject> </screenshot> diff --git a/tde-i18n-en_GB/docs/tdesdk/umbrello/uml_basics.docbook b/tde-i18n-en_GB/docs/tdesdk/umbrello/uml_basics.docbook index dffaa498a57..ee4370f7f4d 100644 --- a/tde-i18n-en_GB/docs/tdesdk/umbrello/uml_basics.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/umbrello/uml_basics.docbook @@ -1,378 +1,169 @@ <chapter id="uml-basics"> -<title ->&UML; Basics</title> +<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, visualise 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 visualise 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> +<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, visualise 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 visualise 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><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 -> +<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> <!-- about-uml --> -<sect1 id="uml-elements" -> -<title ->&UML; Elements</title> +<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> +<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> +<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> + <phrase>&umbrello; showing a Use Case Diagram</phrase> </textobject> <caption> - <para ->&umbrello; showing a Use Case Diagram </para> + <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> +<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> +<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 ->Generalisation</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><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>Generalisation</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> +<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 ->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> +<title>Use Case Description</title> +<para>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> <!-- 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> +<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> +<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> + <phrase>&umbrello; showing a Class Diagram</phrase> </textobject> <caption> - <para ->&umbrello; showing a Class Diagram </para> + <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 behaviour, 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> +<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 behaviour, 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> +<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> + <phrase>Visual representation of a Class in &UML;</phrase> </textobject> <caption> - <para ->Visual representation of a Class in &UML; </para> + <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> +<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> +<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> +<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> +<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> +<title>Class Associations</title> +<para>Classes can relate (be associated with) to each other in different ways:</para> <sect4 id="generalization"> -<title ->Generalisation</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 ->Generalisation</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;, Generalisations are represented by a line connecting the two classes, with an arrow on the side of the base class. <screenshot> -<screeninfo ->Generalisation</screeninfo> +<title>Generalisation</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>Generalisation</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;, Generalisations are represented by a line connecting the two classes, with an arrow on the side of the base class. <screenshot> +<screeninfo>Generalisation</screeninfo> <mediaobject> <imageobject> <imagedata fileref="generalization.png" format="PNG"/> </imageobject> <textobject> - <phrase ->Visual representation of a generalisation in &UML;</phrase> + <phrase>Visual representation of a generalisation in &UML;</phrase> </textobject> <caption> - <para ->Visual representation of a generalisation in &UML; </para> + <para>Visual representation of a generalisation in &UML; </para> </caption> </mediaobject> </screenshot> @@ -380,35 +171,21 @@ </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> +<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> + <phrase>Visual representation of an Association in &UML;</phrase> </textobject> <caption> - <para ->Visual representation of an Association in &UML; </para> + <para>Visual representation of an Association in &UML; </para> </caption> </mediaobject> </screenshot> @@ -416,367 +193,226 @@ </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> +<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> + <phrase>Visual representation of an Aggregation relationship in &UML;</phrase> </textobject> <caption> - <para ->Visual representation of an Aggregation relationship in &UML; </para> + <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> +<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> + <phrase>Visual representation of a Composition relationship in &UML;</phrase> </textobject> </mediaobject> -</screenshot -></para> +</screenshot></para> </sect4> -</sect3 -> <!--class-associations--> +</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> +<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 classes.</para> +<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 classes.</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> +<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> +<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 hundreds of classes.</para> +<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 hundreds of classes.</para> <!-- FIXME screenshot --> </sect4> </sect3> -</sect2 -> <!-- class diagram --> +</sect2> <!-- class diagram --> <sect2 id="sequence-diagram"> -<title ->Sequence Diagrams</title> +<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>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 name and optionally the actual parameter values. </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 name and optionally the actual parameter values. </para> <!-- FIXME update screenshot to show synchronous messages --> <screenshot> -<screeninfo ->Sequence Diagram</screeninfo> +<screeninfo>Sequence Diagram</screeninfo> <mediaobject> <imageobject> <imagedata fileref="sequence-diagram.png" format="PNG"/> </imageobject> <textobject> - <phrase ->&umbrello; showing a Sequence Diagram</phrase> + <phrase>&umbrello; showing a Sequence Diagram</phrase> </textobject> <caption> - <para ->&umbrello; showing a Sequence Diagram </para> + <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 --> +<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> +<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>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> +<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> +<screeninfo>Collaboration</screeninfo> <mediaobject> <imageobject> <imagedata fileref="collaboration-diagram.png" format="PNG"/> </imageobject> <textobject> - <phrase ->&umbrello; showing a Collaboration Diagram</phrase> + <phrase>&umbrello; showing a Collaboration Diagram</phrase> </textobject> <caption> - <para ->&umbrello; showing a Collaboration Diagram </para> + <para>&umbrello; showing a Collaboration Diagram </para> </caption> </mediaobject> </screenshot> -</sect2 -> <!-- collaboration diagrams --> +</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 exhibit Objects as <emphasis ->state machines</emphasis -> or finite automata that can be in one of a finite set of 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> +<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 exhibit Objects as <emphasis>state machines</emphasis> or finite automata that can be in one of a finite set of 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> +<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> +<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> +<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> +<screeninfo>State Diagram</screeninfo> <mediaobject> <imageobject> <imagedata fileref="state-diagram.png" format="PNG"/> </imageobject> <textobject> - <phrase ->&umbrello; showing a State Diagram</phrase> + <phrase>&umbrello; showing a State Diagram</phrase> </textobject> <caption> - <para ->&umbrello; showing a State Diagram </para> + <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 possibly take an Object out of its End state once it has reached it. </para> +<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 possibly take an Object out of its End state once it has reached it. </para> </sect3> -</sect2 -> <!-- state diagrams --> +</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> +<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> +<screeninfo>An example Activity Diagram.</screeninfo> <mediaobject> <imageobject> <imagedata fileref="activity-diagram.png" format="PNG"/> </imageobject> <textobject> - <phrase ->&umbrello; showing an Activity Diagram</phrase> + <phrase>&umbrello; showing an Activity Diagram</phrase> </textobject> <caption> - <para ->&umbrello; showing an Activity Diagram </para> + <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> +<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> +<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> <!-- 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> +<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> +<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> <!-- 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 artefacts they are made out of such as source code files, programming libraries or relational database tables.</para> +<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 artefacts 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> +<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> +<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> +<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 -> +</sect1> </chapter> diff --git a/tde-i18n-en_GB/docs/tdesdk/umbrello/working_with_umbrello.docbook b/tde-i18n-en_GB/docs/tdesdk/umbrello/working_with_umbrello.docbook index ffa6cbf2bf7..2aeba7660cc 100644 --- a/tde-i18n-en_GB/docs/tdesdk/umbrello/working_with_umbrello.docbook +++ b/tde-i18n-en_GB/docs/tdesdk/umbrello/working_with_umbrello.docbook @@ -1,411 +1,188 @@ <chapter id="working-with-umbrello"> -<title ->Working with &umbrello;</title> +<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> +<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> +<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> +<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> +<screeninfo>&umbrello;'s User Interface</screeninfo> <mediaobject> <imageobject> <imagedata fileref="umbrello-ui.png" format="PNG"/> </imageobject> <textobject> - <phrase ->&umbrello;'s User Interface</phrase> + <phrase>&umbrello;'s User Interface</phrase> </textobject> <caption> - <para ->&umbrello;'s User Interface </para> + <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 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 organising 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 organise your elements by moving them to the appropriate folder (drag and drop) </para> +<title>Tree View</title> +<para>The Tree View is usually located on the top left hand side of the window and shows 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 organising 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 organise your elements by moving them to the appropriate folder (drag and drop) </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> +<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> +<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> <!--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 dialogue). This will allow you to start working right away. </para> +<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 dialogue). 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> +<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> +<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> +<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> <!--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> +<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 dialogue, 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> +<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 dialogue, 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> +<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> +<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> +<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 dialogue, which you obtain by selecting Properties from its Context Menu or by double clicking on it in the Tree View. </para> +<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 dialogue, 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 colour 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> +<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 colour 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> +<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> +<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> +<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> +<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 dialogue 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 dialogue 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 colours you want to use for the line and fill of the class' representation on the diagram. </para> +<title>Editing Elements</title> +<para>You can edit most of the &UML; elements in your model and diagrams by opening its Properties dialogue 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 dialogue 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 colours 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 dialogue 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 dialogue. </para> +<para>For most &UML; elements you can also open the properties dialogue 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 dialogue. </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> +<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 dialogue for a class you can set everything, from the colour it uses to the operations and attributes it has. </para> +<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 dialogue for a class you can set everything, from the colour 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 dialogue is self-explanatory. Here you can change the class' name, visibility, documentation, &etc; This page is always available. </para> +<title>Class General Settings</title> +<para>The General Settings page of the properties dialogue 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> +<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 -> dialogue. 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 -> dialogue. This page is always available </para> +<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> dialogue. 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> dialogue. 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> +<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 dialogue 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> +<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 dialogue 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 operations 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> +<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 operations 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 Colour Page</title> -<para ->In the <guilabel ->Widget Colour</guilabel -> page you can configure the colours 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 dialogue from the Tree View. </para> +<title>Class Colour Page</title> +<para>In the <guilabel>Widget Colour</guilabel> page you can configure the colours 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 dialogue 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 exist 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 of the objects participating in the association, it is <emphasis ->not</emphasis -> a drag from one object to the other. </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 Generalisation exists from class A to class B and then you try to create another Generalisation 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> +<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 exist 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 of the objects participating in the association, it is <emphasis>not</emphasis> a drag from one object to the other. </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 Generalisation exists from class A to class B and then you try to create another Generalisation 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> +<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> +<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> +<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> |