From 0b8ca6637be94f7814cafa7d01ad4699672ff336 Mon Sep 17 00:00:00 2001 From: Darrell Anderson Date: Tue, 21 Jan 2014 22:06:48 -0600 Subject: Beautify docbook files --- tde-i18n-en_GB/docs/tdesdk/cervisia/index.docbook | 3842 ++++---------------- tde-i18n-en_GB/docs/tdesdk/kbabel/catman.docbook | 166 +- .../docs/tdesdk/kbabel/dictionaries.docbook | 554 +-- tde-i18n-en_GB/docs/tdesdk/kbabel/faq.docbook | 71 +- tde-i18n-en_GB/docs/tdesdk/kbabel/glossary.docbook | 243 +- tde-i18n-en_GB/docs/tdesdk/kbabel/index.docbook | 139 +- .../docs/tdesdk/kbabel/kbabeldict.docbook | 70 +- tde-i18n-en_GB/docs/tdesdk/kbabel/menu.docbook | 1744 ++------- .../docs/tdesdk/kbabel/preferences.docbook | 1106 +----- tde-i18n-en_GB/docs/tdesdk/kbabel/using.docbook | 924 +---- .../docs/tdesdk/kbugbuster/index.docbook | 67 +- tde-i18n-en_GB/docs/tdesdk/kompare/index.docbook | 67 +- .../docs/tdesdk/tdecachegrind/index.docbook | 930 ++--- .../docs/tdesdk/umbrello/authors.docbook | 53 +- .../umbrello/code_import_and_generation.docbook | 155 +- .../docs/tdesdk/umbrello/credits.docbook | 11 +- tde-i18n-en_GB/docs/tdesdk/umbrello/index.docbook | 56 +- .../docs/tdesdk/umbrello/introduction.docbook | 66 +- .../docs/tdesdk/umbrello/other_features.docbook | 67 +- .../docs/tdesdk/umbrello/uml_basics.docbook | 726 +--- .../tdesdk/umbrello/working_with_umbrello.docbook | 425 +-- 21 files changed, 2128 insertions(+), 9354 deletions(-) (limited to 'tde-i18n-en_GB/docs/tdesdk') 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 @@ - ssh"> - rsh"> + ssh"> + rsh"> - - CVS"> + + CVS"> ]> -&cervisia; Manual +&cervisia; Manual -BerndGehrmann
bernd@mail.berlios.de
 - -CarlosWoelz
carloswoelz@imap-mail.com
 - - - -AlexWalker
alex@x3ja.co.uk
Conversion to British English +BerndGehrmann
bernd@mail.berlios.de
 + +CarlosWoelz
carloswoelz@imap-mail.com
 + + + +AlexWalker
alex@x3ja.co.uk
Conversion to British English -1999 -2000 -2001 -2002 -Bernd Gehrmann +1999 +2000 +2001 +2002 +Bernd Gehrmann -2004 -Carlos Woelz +2004 +Carlos Woelz -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. +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. -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. +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. -&FDLNotice; +&FDLNotice; -2004-06-06 -2.01.90 +2004-06-06 +2.01.90 -&cervisia; provides a graphical view of &CVS;. +&cervisia; provides a graphical view of &CVS;. -KDE -tdesdk -Cervisia -CVS -version control -revision control +KDE +tdesdk +Cervisia +CVS +version control +revision control -Introduction +Introduction -&cervisia; 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. +&cervisia; 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. -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. +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. -The main repository 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;. +The main repository 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;. -The repository holds the project files, and every contributor keeps their own local copy, named working copy or sandbox; 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. +The repository holds the project files, and every contributor keeps their own local copy, named working copy or sandbox; 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. -Getting Started +Getting Started -Accessing The Repository +Accessing The Repository -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. +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. -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. +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. -Creating a Local Repository - -Open the Create New Repository (cvs init) dialogue by choosing Repository Create.... - -Press the ... 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 /home/user folder, and to name it cvsroot, you should type /home/user/cvsroot in the edit box, or select the /home/user folder using the file picker and add cvsroot. - -Confirm by pressing the OK button. &cervisia; will create and initialise the new repository folder. - -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. +Creating a Local Repository + +Open the Create New Repository (cvs init) dialogue by choosing Repository Create.... + +Press the ... 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 /home/user folder, and to name it cvsroot, you should type /home/user/cvsroot in the edit box, or select the /home/user folder using the file picker and add cvsroot. + +Confirm by pressing the OK button. &cervisia; will create and initialise the new repository folder. + +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. -&cervisia; offers an integrated front-end to manage all your repository locations, the Configure Access to Repositories dialogue. To display it, select the Repository Repositories... menu item. +&cervisia; offers an integrated front-end to manage all your repository locations, the Configure Access to Repositories dialogue. To display it, select the Repository Repositories... menu item.
-A screenshot of &cervisia;'s Configure Access to Repositories dialogue +A screenshot of &cervisia;'s Configure Access to Repositories dialogue - -A screenshot of &cervisia;'s Configure Access to Repositories dialogue + +A screenshot of &cervisia;'s Configure Access to Repositories dialogue
-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): +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): -[:method:][[user][:password]@]hostname[:[port]]/path/to/repository +[:method:][[user][:password]@]hostname[:[port]]/path/to/repository -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: +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: -Local +Local -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 /path/to/repository or to give a real life example, /home/cvs. - -It may physically be on a disk which is mounted via NFS, but this is an irrelevant detail. If you created a local repository, the location will be simple the path to it. +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 /path/to/repository or to give a real life example, /home/cvs. + +It may physically be on a disk which is mounted via NFS, but this is an irrelevant detail. If you created a local repository, the location will be simple the path to it. -rsh +rsh -The repository location is something like :ext:username@host.url.org:/path/to/repository. - -This method requires that you have a user account on the server machine (in this example, host.url.org) 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;. - -If you wish to use &ssh;, you must set the environment variable $CVS_RSH to &ssh; when using the cvs client. &cervisia; supports this easily. +The repository location is something like :ext:username@host.url.org:/path/to/repository. + +This method requires that you have a user account on the server machine (in this example, host.url.org) 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;. + +If you wish to use &ssh;, you must set the environment variable $CVS_RSH to &ssh; when using the cvs client. &cervisia; supports this easily. -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 .rhosts file in your home folder with a list of trusted hosts (see the ↱ manpage). - -With &ssh;, it can be achieved by copying your public key located in the file identity.pub, located in the $HOME/.ssh/ folder to the server. In this case, the key must not be encrypted with a passphrase see the &ssh; manpage and the &CVS;/SSH FAQ on SourceForge). If you are unsure about these issues, ask your system administrator. +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 .rhosts file in your home folder with a list of trusted hosts (see the ↱ manpage). + +With &ssh;, it can be achieved by copying your public key located in the file identity.pub, located in the $HOME/.ssh/ folder to the server. In this case, the key must not be encrypted with a passphrase see the &ssh; manpage and the &CVS;/SSH FAQ on SourceForge). If you are unsure about these issues, ask your system administrator. -pserver +pserver -The repository location looks like :pserver:username@host.url.org:/path/to/repository +The repository location looks like :pserver:username@host.url.org:/path/to/repository -This method accesses the server via a special protocol with a relatively weak authentication (pserver 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. +This method accesses the server via a special protocol with a relatively weak authentication (pserver 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. -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. +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. -Knowing the access method and location to the repository, you can add it to &cervisia;'s repositories list: +Knowing the access method and location to the repository, you can add it to &cervisia;'s repositories list: -Adding a New Repository - -Open the Configure Access to Repositories dialogue by choosing the Repository Repositories... menu item. - -Press the Add... button to open the Add Repository dialogue. - -Enter the repository location in the Repository: edit box. &cervisia; will automatically disable the areas of the dialogue that are not relevant to the access method you entered. - -If you are using the ext method to access the repository, enter the remote shell you wish to use (⪚ &ssh;) in the Use remote shell edit box. - -Press OK. You will see the repository you just entered on the repositories list. - -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 Login... button. Enter your password in the pop-up dialogue. -If you successfully enter your password, the Status column entry of the pserver repository will change from Not logged in to Logged in. - -Press OK to apply your modifications, or add another location to the list. &cervisia; will store as many locations as you like. +Adding a New Repository + +Open the Configure Access to Repositories dialogue by choosing the Repository Repositories... menu item. + +Press the Add... button to open the Add Repository dialogue. + +Enter the repository location in the Repository: edit box. &cervisia; will automatically disable the areas of the dialogue that are not relevant to the access method you entered. + +If you are using the ext method to access the repository, enter the remote shell you wish to use (⪚ &ssh;) in the Use remote shell edit box. + +Press OK. You will see the repository you just entered on the repositories list. + +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 Login... button. Enter your password in the pop-up dialogue. +If you successfully enter your password, the Status column entry of the pserver repository will change from Not logged in to Logged in. + +Press OK to apply your modifications, or add another location to the list. &cervisia; will store as many locations as you like. @@ -421,376 +193,150 @@ -Importing a Module Into the Repository +Importing a Module Into the Repository -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. +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. -There are two ways to put a project into the &CVS;: +There are two ways to put a project into the &CVS;: -Import the files and folders to a new module, 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. +Import the files and folders to a new module, 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. -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. +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. -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 explicitly tell CVS if it is a text or binary file. If you declare the wrong file type, you will experience problems with the &CVS; functionality for these files, and they may get corrupted. +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 explicitly tell CVS if it is a text or binary file. If you declare the wrong file type, you will experience problems with the &CVS; functionality for these files, and they may get corrupted. -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. +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. -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 *.png 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 checkout the newly imported module to a new working copy, copy the the missing files and folders to it, add and commit them to the repository to complete the import process. +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 *.png 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 checkout the newly imported module to a new working copy, copy the the missing files and folders to it, add and commit them to the repository to complete the import process. -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. Checkout the new empty module. Then copy the the files and folders to the working copy, add and commit to upload them to the &CVS; repository. +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. Checkout the new empty module. Then copy the the files and folders to the working copy, add and commit to upload them to the &CVS; repository.
-A screenshot of &cervisia;'s import dialogue +A screenshot of &cervisia;'s import dialogue - -A screenshot of &cervisia;'s import dialogue + +A screenshot of &cervisia;'s import dialogue
-In you can see the dialogue which helps you to import a project as a module. To access &cervisia;'s import dialogue, choose the Repository Import... menu item. +In you can see the dialogue which helps you to import a project as a module. To access &cervisia;'s import dialogue, choose the Repository Import... menu item. -Repository: -Enter or select on the dropdown list the name of the &CVS; repository, also known as $CVSROOT. 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 Repository Create... menu item. -The drop down box shows a list of the repositories you previously entered using the Configure Access to Repositories dialogue box. If the repository is remote, make sure that authentication works. See for more information. +Repository: +Enter or select on the dropdown list the name of the &CVS; repository, also known as $CVSROOT. 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 Repository Create... menu item. +The drop down box shows a list of the repositories you previously entered using the Configure Access to Repositories dialogue box. If the repository is remote, make sure that authentication works. See for more information. -Module: -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 for more information. This is also the name of the corresponding folder in the repository. +Module: +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 for more information. This is also the name of the corresponding folder in the repository. -Working Folder: -The toplevel folder of the project you want to import. The import starts from this folder and goes down recursively. +Working Folder: +The toplevel folder of the project you want to import. The import starts from this folder and goes down recursively. -Vendor tag: -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. +Vendor tag: +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. -Release tag: -This tag is also historically used for importing different versions of third-party software. If you are not doing this, use the word start or a string FOO_1_0 where FOO is the name of your project and 1.0 is the version number of the imported release. +Release tag: +This tag is also historically used for importing different versions of third-party software. If you are not doing this, use the word start or a string FOO_1_0 where FOO is the name of your project and 1.0 is the version number of the imported release. -Ignore files: -If you fill out this field, an additional option is given go the cvs import 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 core. In such a case, simply enter the character ! in this field: this overrules &CVS;'s scheme of ignored files, see . +Ignore files: +If you fill out this field, an additional option is given go the cvs import 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 core. In such a case, simply enter the character ! in this field: this overrules &CVS;'s scheme of ignored files, see . -Comment: -Use this field to record the comments you might have about the origin, use, development &etc; of the files you are importing. +Comment: +Use this field to record the comments you might have about the origin, use, development &etc; of the files you are importing. -Import as binaries -If you check this box, all files are imported in binary mode, i.e. an argument is given to cvs import. +Import as binaries +If you check this box, all files are imported in binary mode, i.e. an argument is given to cvs import. -Use file's modification as time of import -If you check this box, the time of import will be the file's modification time instead of the import time. +Use file's modification as time of import +If you check this box, the time of import will be the file's modification time instead of the import time. -After you have filled out this form and confirmed by pressing OK, the following &CVS; command is used: - -cvs -d repository import -m "" module vendortag releasetag +After you have filled out this form and confirmed by pressing OK, the following &CVS; command is used: + +cvs -d repository import -m "" module vendortag releasetag -Checkout a Module From the Repository -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. +Checkout a Module From the Repository +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. -You should also know the name of the branch or tag you want to use. +You should also know the name of the branch or tag you want to use. -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. +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. -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;. +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;.
-A screenshot of &cervisia;'s checkout dialogue +A screenshot of &cervisia;'s checkout dialogue - -A screenshot of &cervisia;'s checkout dialogue + +A screenshot of &cervisia;'s checkout dialogue
-Repository: -The name of the &CVS; repository, also known as $CVSROOT. The drop-down box shows a list of the repositories you previously entered using the Configure Access to Repositories dialogue box. If the repository is remote, make sure that authentication works. See for more information. +Repository: +The name of the &CVS; repository, also known as $CVSROOT. The drop-down box shows a list of the repositories you previously entered using the Configure Access to Repositories dialogue box. If the repository is remote, make sure that authentication works. See for more information. -Module: -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. -Alternatively, if the repository has a $CVSROOT/modules file, you can retrieve a list of available modules by pressing the Fetch list button. -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 doc/cervisia subfolder of the tdesdk module, enter tdesdk/doc/cervisia in this field. +Module: +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. +Alternatively, if the repository has a $CVSROOT/modules file, you can retrieve a list of available modules by pressing the Fetch list button. +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 doc/cervisia subfolder of the tdesdk module, enter tdesdk/doc/cervisia in this field. -Branch tag: -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. +Branch tag: +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. -Working folder: -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 Check out as: field. +Working folder: +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 Check out as: field. -Check out as: -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. +Check out as: +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. -Export only -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. +Export only +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. @@ -799,242 +345,96 @@ -The Main Screen, Viewing File Status and Updating -When you start &cervisia;, and open a working copy by choosing File Open Sandbox... , 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. - -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 View Unfold File Tree . To close back all folders from the working copy, choose View Fold File Tree . - -According to the settings in your .cvsignore 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 File Update or File Status . With this approach, you have a minimal amount of functionality available even if you do not have a permanent connection to the &CVS; server. +The Main Screen, Viewing File Status and Updating +When you start &cervisia;, and open a working copy by choosing File Open Sandbox... , 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. + +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 View Unfold File Tree . To close back all folders from the working copy, choose View Fold File Tree . + +According to the settings in your .cvsignore 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 File Update or File Status . With this approach, you have a minimal amount of functionality available even if you do not have a permanent connection to the &CVS; server.
-A screenshot of &cervisia;'s main view +A screenshot of &cervisia;'s main view - -A screenshot of &cervisia;'s main view + +A screenshot of &cervisia;'s main view
-The commands in the File menu usually act only on the files which you have marked. You may also mark folders. Now choose Status from the File menu, press F5 or right click the marked files and choose the Status menu item from the pop-up menu. &cervisia; issues a +The commands in the File menu usually act only on the files which you have marked. You may also mark folders. Now choose Status from the File menu, press F5 or right click the marked files and choose the Status menu item from the pop-up menu. &cervisia; issues a -cvs update -n file names +cvs update -n file names -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 Settings menu set. According to the respective file's status, you now see an entry in the Status column: +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 Settings menu set. According to the respective file's status, you now see an entry in the Status column: -Locally Modified -This means you have modified the file compared to the version in the repository. +Locally Modified +This means you have modified the file compared to the version in the repository. -Locally Added -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. +Locally Added +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. -Locally Removed -This means you have scheduled the file for removal, but it still exists in the repository. The actual removal happens only after a commit. +Locally Removed +This means you have scheduled the file for removal, but it still exists in the repository. The actual removal happens only after a commit. -Needs Update -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. +Needs Update +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. -Needs Patch -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. +Needs Patch +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. -Needs Merge -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". +Needs Merge +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". -Up to Date -Indicates that the file is identical with the version in the repository. +Up to Date +Indicates that the file is identical with the version in the repository. -Conflict -This is shown if this file still has conflict markers in it. Maybe you have previously updated the file and not resolved the conflicts. +Conflict +This is shown if this file still has conflict markers in it. Maybe you have previously updated the file and not resolved the conflicts. -Not In CVS -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 .cvsignore file. +Not In CVS +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 .cvsignore file. -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 Update from the File menu, or right-click the marked files and choose the Status 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: +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 Update from the File menu, or right-click the marked files and choose the Status 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: -Updated -Shown if the file was updated from the repository. +Updated +Shown if the file was updated from the repository. -Patched -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 Conflict. +Patched +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 Conflict. -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 Status 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 File name column. +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 Status 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 File name column. @@ -1042,404 +442,156 @@ -Working With Files - -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 Settings menu. For example, if SettingsCommit and Remove Recursively is checked and you choose FileCommit... 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. +Working With Files + +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 Settings menu. For example, if SettingsCommit and Remove Recursively is checked and you choose FileCommit... 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.
-A screenshot of &cervisia;'s pop-up menu +A screenshot of &cervisia;'s pop-up menu - +
-The most used actions are also available by right-clicking the files in the tree view, through the pop-up menu. shows &cervisia;'s main window pop-up menu. +The most used actions are also available by right-clicking the files in the tree view, through the pop-up menu. shows &cervisia;'s main window pop-up menu. -You can simply edit a file by double-clicking on it or selecting it and pressing Return. 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 Edit With submenu, and select one of the other applications that handle that file type. +You can simply edit a file by double-clicking on it or selecting it and pressing Return. 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 Edit With submenu, and select one of the other applications that handle that file type. -Adding Files - -Adding files to a project requires two steps: first, the files must be registered with &CVS;, or in other words, added to the repository. This is necessary, but not sufficient. In order to actually put the files into the repository, you must commit 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. - -To this end, mark all files to be added in &cervisia;'s main view. Then, choose FileAdd to Repository..., or right click the marked files and choose Add to Repository.... The CVS Add dialogue will appear, listing the files you marked, and asks for confirmation. Press OK. - -&cervisia; issues a command +Adding Files + +Adding files to a project requires two steps: first, the files must be registered with &CVS;, or in other words, added to the repository. This is necessary, but not sufficient. In order to actually put the files into the repository, you must commit 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. + +To this end, mark all files to be added in &cervisia;'s main view. Then, choose FileAdd to Repository..., or right click the marked files and choose Add to Repository.... The CVS Add dialogue will appear, listing the files you marked, and asks for confirmation. Press OK. + +&cervisia; issues a command -cvs add file names +cvs add file names -If the operation was successful, the status column should have "Added to repository" for the added files. - -&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 $Revision: 1.6 $) when a file is committed. In binary files, such replacements may corrupt the file and make it completely unusable. - -In order to switch the above behaviour off, you should commit binary files (or other files, like Postscript or PNG images) by choosing FileAdd Binary.... The CVS Add dialogue will appear, listing the binary files you marked, and asks for confirmation. Press OK. - -&cervisia; issues a command +If the operation was successful, the status column should have "Added to repository" for the added files. + +&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 $Revision: 1.6 $) when a file is committed. In binary files, such replacements may corrupt the file and make it completely unusable. + +In order to switch the above behaviour off, you should commit binary files (or other files, like Postscript or PNG images) by choosing FileAdd Binary.... The CVS Add dialogue will appear, listing the binary files you marked, and asks for confirmation. Press OK. + +&cervisia; issues a command -cvs add -kb file names +cvs add -kb file names -Removing Files - -Like adding files, removing files is done in two steps: First, the files have to be registered as removed by choosing FileRemove From Repository... or right clicking the marked files and choosing Remove From Repository... from the pop-up menu. The CVS Remove dialogue will appear, listing the files you marked, and asking for confirmation. Press OK. &cervisia; issues the command +Removing Files + +Like adding files, removing files is done in two steps: First, the files have to be registered as removed by choosing FileRemove From Repository... or right clicking the marked files and choosing Remove From Repository... from the pop-up menu. The CVS Remove dialogue will appear, listing the files you marked, and asking for confirmation. Press OK. &cervisia; issues the command -cvs remove -f file names +cvs remove -f file names -After that, this modification to the sandbox has to be committed, possibly together with other modifications to the project. +After that, this modification to the sandbox has to be committed, possibly together with other modifications to the project. -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. +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. -Adding and Removing Folders - -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). - -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 to cvs update and cvs checkout. This option can be set in the menu SettingsPrune Empty Folders on Update. - -A folder can be added to the repository choosing FileAdd to Repository... or right clicking the marked folder and choosing Add to Repository... from the pop-up menu. Note that in contrast to adding files, adding folders does not require a commit afterwards. &cervisia; issues the command +Adding and Removing Folders + +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). + +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 to cvs update and cvs checkout. This option can be set in the menu SettingsPrune Empty Folders on Update. + +A folder can be added to the repository choosing FileAdd to Repository... or right clicking the marked folder and choosing Add to Repository... from the pop-up menu. Note that in contrast to adding files, adding folders does not require a commit afterwards. &cervisia; issues the command -cvs add dirname +cvs add dirname -Committing Files - -When you have made a certain number of changes to your working copy, and you want other developers to have access to them, you commit 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. - -In order to commit a couple of files, select them in &cervisia;'s main view and choose FileCommit... or right click the marked files and choose Commit... from the pop-up menu. +Committing Files + +When you have made a certain number of changes to your working copy, and you want other developers to have access to them, you commit 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. + +In order to commit a couple of files, select them in &cervisia;'s main view and choose FileCommit... or right click the marked files and choose Commit... from the pop-up menu.
-A screenshot of &cervisia;'s commit dialogue +A screenshot of &cervisia;'s commit dialogue - +
-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 Return 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 +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 Return 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 -cvs commit -m message file names +cvs commit -m message file names -is used. +is used. -A common error you may encounter when committing is Up-to-date check failed. This indicates that someone has committed changes to the repository since you last updated; or, more technically, that your BASE 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. +A common error you may encounter when committing is Up-to-date check failed. This indicates that someone has committed changes to the repository since you last updated; or, more technically, that your BASE 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. -Another popular mistake results in the error message Sticky tag 'X' for file 'X' is not a branch. This happens if you try to commit a file which you have previously brought to a certain revision or tag with the command +Another popular mistake results in the error message Sticky tag 'X' for file 'X' is not a branch. This happens if you try to commit a file which you have previously brought to a certain revision or tag with the command -%cvs update -r X +%cvs update -r X -(which is ⪚ used by the menu item AdvancedUpdate to Tag/Date...). 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. +(which is ⪚ used by the menu item AdvancedUpdate to Tag/Date...). 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. -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 FileInsert ChangeLog Entry.... If a file with the name ChangeLog 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 ) is inserted. When you finish the dialogue this dialogue by clicking OK, the next commit dialogue you open will have the log message set to the message you last entered in the ChangeLog. +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 FileInsert ChangeLog Entry.... If a file with the name ChangeLog 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 ) is inserted. When you finish the dialogue this dialogue by clicking OK, the next commit dialogue you open will have the log message set to the message you last entered in the ChangeLog. -Resolving Conflicts +Resolving Conflicts -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. +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. -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. +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. -&CVS; marks the conflicting changes by placing marks in the middle of the files, in the following manner: +&CVS; marks the conflicting changes by placing marks in the middle of the files, in the following manner: -<<<<<<< +<<<<<<< Changes in your working copy ======= Changes in the repository >>>>>>> revision_number -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. - -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 CVS Resolve dialogue choose FileResolve... or right click the marked file and choose Resolve... from the pop-up menu. +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. + +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 CVS Resolve dialogue choose FileResolve... or right click the marked file and choose Resolve... from the pop-up menu.
-A screenshot of &cervisia;'s resolve dialogue +A screenshot of &cervisia;'s resolve dialogue - -A screenshot of &cervisia;'s resolve dialogue + +A screenshot of &cervisia;'s resolve dialogue
-On the top of the dialogue, you see Your version (A) of the file on the left hand side and the version in the repository, Other version (B), on the right hand side. The differences between them are marked in red colour. Below these two versions, you can see the Merged version. The merged version reflects what that section will be in your working copy if you press the Save button. - -You can go back and forward between the conflicting sections by pressing << and >>. In the lower middle of the dialogue you can see which section is currently marked. For example, 2 of 3 means that you are currently at the second differing section of 3 total. - -Now can can decide section by section which version you want to have in the merged file. By pressing A, you take over the version you edited. By pressing B, you take over the version from the repository. By pressing A+B, both versions will be added, and your version will come first. B+A yields the same result, but the order will be different: first the repository version, then yours. - -If you are not happy with any of these versions, press Edit to open a simple text editor where you can edit the section. When you are finished editing, press OK to return to the CVS Resolve dialogue and resume solving conflicts. You will see the section you just edited in the Merged version, with your modifications. - -To save your modifications, overwriting the working copy version, press Save. 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 Save As.... Press Close to exit the dialogue. If you close the dialogue without saving, the changes you made will be lost. +On the top of the dialogue, you see Your version (A) of the file on the left hand side and the version in the repository, Other version (B), on the right hand side. The differences between them are marked in red colour. Below these two versions, you can see the Merged version. The merged version reflects what that section will be in your working copy if you press the Save button. + +You can go back and forward between the conflicting sections by pressing << and >>. In the lower middle of the dialogue you can see which section is currently marked. For example, 2 of 3 means that you are currently at the second differing section of 3 total. + +Now can can decide section by section which version you want to have in the merged file. By pressing A, you take over the version you edited. By pressing B, you take over the version from the repository. By pressing A+B, both versions will be added, and your version will come first. B+A yields the same result, but the order will be different: first the repository version, then yours. + +If you are not happy with any of these versions, press Edit to open a simple text editor where you can edit the section. When you are finished editing, press OK to return to the CVS Resolve dialogue and resume solving conflicts. You will see the section you just edited in the Merged version, with your modifications. + +To save your modifications, overwriting the working copy version, press Save. 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 Save As.... Press Close to exit the dialogue. If you close the dialogue without saving, the changes you made will be lost. @@ -1447,638 +599,245 @@ Changes in the repository -Obtaining Information About Files and Creating Patches +Obtaining Information About Files and Creating Patches -Watching Differences Between Revisions +Watching Differences Between Revisions -There are several places in &cervisia; where you can ask for a window showing the differences between revisions of a file: +There are several places in &cervisia; where you can ask for a window showing the differences between revisions of a file: -In the main view, you can choose ViewDifference to Repository (BASE).... This is based on the command cvs diff and shows you the differences between the version in your sandbox and the version to which you last updated (also known as BASE). This is in particular useful just before you commit a file, so you can find an appropriate log message. - -You can view the differences between the version in your sandbox and the version in the main development branch (also called HEAD) by choosing View Difference to Repository (HEAD).... - -You can view the differences between the last two revisions of the selected file choosing View Last Change.... - -You can access the Difference to Repository (BASE)..., Difference to Repository (HEAD)... and Last Change... menu items from the main view pop-up menu, by right-clicking the file you want to view. - -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 Return. This is quite similar to using ViewDifference to Repository (BASE)... with the respective file in the main view. - -In the Browse Logs dialogue, you can mark two revisions of a file and request a dialogue showing the differences between them (see ). +In the main view, you can choose ViewDifference to Repository (BASE).... This is based on the command cvs diff and shows you the differences between the version in your sandbox and the version to which you last updated (also known as BASE). This is in particular useful just before you commit a file, so you can find an appropriate log message. + +You can view the differences between the version in your sandbox and the version in the main development branch (also called HEAD) by choosing View Difference to Repository (HEAD).... + +You can view the differences between the last two revisions of the selected file choosing View Last Change.... + +You can access the Difference to Repository (BASE)..., Difference to Repository (HEAD)... and Last Change... menu items from the main view pop-up menu, by right-clicking the file you want to view. + +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 Return. This is quite similar to using ViewDifference to Repository (BASE)... with the respective file in the main view. + +In the Browse Logs dialogue, you can mark two revisions of a file and request a dialogue showing the differences between them (see ). -As you may have expected, &cervisia; does not just dump the output of the diff command into your terminal, but shows you a graphical view as seen in . +As you may have expected, &cervisia; does not just dump the output of the diff command into your terminal, but shows you a graphical view as seen in .
-A screenshot of &cervisia;'s diff dialogue +A screenshot of &cervisia;'s diff dialogue - -A screenshot of &cervisia;'s diff dialogue + +A screenshot of &cervisia;'s diff dialogue
-The text in the dialogue is an improved variant of the text given by the diff command with the 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 +++++ at the left hand side. Elsewhere, you can see the running number of each line in the left column. - -In the second column in the right window, you can see which kind of change has been made. Possible types are Add, Delete and Change. 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. - -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 Synchronise scroll bars. - -For information about how to customise the diff dialogue, see . +The text in the dialogue is an improved variant of the text given by the diff command with the 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 +++++ at the left hand side. Elsewhere, you can see the running number of each line in the left column. + +In the second column in the right window, you can see which kind of change has been made. Possible types are Add, Delete and Change. 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. + +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 Synchronise scroll bars. + +For information about how to customise the diff dialogue, see . -Creating Patches - -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 patch, and is generated by the cvs diff command, in the same way as the differences in . 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. - -&cervisia; gives you to access to this feature by choosing Advanced Create Patch Against Repository. - -The Create Patch Against Repository action creates a patch with all modifications in all files in your working copy (sandbox) against the BASE repository. Therefore, the selection of files in the main view does not affect the patch that will be generated. - -Another possibility is to select one file in the main view and choose Browse Log... from the View menu or right click the marked file and choose Browse Log... from the pop-up menu, in order to open the Browse log dialogue. Now, select the version you want to create a patch against, as revision "A" and press the button Create Patch.... This will generate a patch with the differences between the marked file in your working copy and the version selected as revision "A". - -Before generating the patch, &cervisia; displays a dialogue allowing you to configure the output format. +Creating Patches + +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 patch, and is generated by the cvs diff command, in the same way as the differences in . 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. + +&cervisia; gives you to access to this feature by choosing Advanced Create Patch Against Repository. + +The Create Patch Against Repository action creates a patch with all modifications in all files in your working copy (sandbox) against the BASE repository. Therefore, the selection of files in the main view does not affect the patch that will be generated. + +Another possibility is to select one file in the main view and choose Browse Log... from the View menu or right click the marked file and choose Browse Log... from the pop-up menu, in order to open the Browse log dialogue. Now, select the version you want to create a patch against, as revision "A" and press the button Create Patch.... This will generate a patch with the differences between the marked file in your working copy and the version selected as revision "A". + +Before generating the patch, &cervisia; displays a dialogue allowing you to configure the output format.
-A screenshot of &cervisia;'s patch dialogue +A screenshot of &cervisia;'s patch dialogue - -A screenshot of &cervisia;'s patch dialogue + +A screenshot of &cervisia;'s patch dialogue
-Output Format -There are three output formats available: -Normal: 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. -Unified: 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. -Context, 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. +Output Format +There are three output formats available: +Normal: 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. +Unified: 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. +Context, 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. -Number of context lines: -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. +Number of context lines: +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. -Ignore Options -Check here the changes that should not be considered as differences when generating the patch. +Ignore Options +Check here the changes that should not be considered as differences when generating the patch. -After setting the output format, &cervisia; generates the patch and displays the Save As dialogue. Enter in this dialogue the file name and location of the patch file. +After setting the output format, &cervisia; generates the patch and displays the Save As dialogue. Enter in this dialogue the file name and location of the patch file. -Watching an Annotated View of a File - -With the command cvs annotate, &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. - -&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 ViewAnnotate.... Another possibility is to press the button Annotate in the Browse log dialogue, in which you can select which version of the file you want to display. In you can see a screenshot of the dialogue. +Watching an Annotated View of a File + +With the command cvs annotate, &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. + +&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 ViewAnnotate.... Another possibility is to press the button Annotate in the Browse log dialogue, in which you can select which version of the file you want to display. In you can see a screenshot of the dialogue.
-A screenshot of &cervisia;'s annotate dialogue +A screenshot of &cervisia;'s annotate dialogue - -A screenshot of &cervisia;'s annotate dialogue + +A screenshot of &cervisia;'s annotate dialogue
-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 Browse log dialogue). 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. +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 Browse log dialogue). 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. -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 why 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. +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 why 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. -Browsing &CVS; Logs - -When you mark one file in the main view and choose Browse Log... from the View menu or right click the marked file and choose Browse Log... from the pop-up menu, the CVS Log 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: +Browsing &CVS; Logs + +When you mark one file in the main view and choose Browse Log... from the View menu or right click the marked file and choose Browse Log... from the pop-up menu, the CVS Log 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: -View the revision, author, date, branch, commit message and tags for each version of the marked file. +View the revision, author, date, branch, commit message and tags for each version of the marked file. -View a graphical tree representation showing the branching and tagging of the marked file. +View a graphical tree representation showing the branching and tagging of the marked file. -View any version of the marked file (with the default application). +View any version of the marked file (with the default application). -Watch an annotated view of any version of the marked file +Watch an annotated view of any version of the marked file -View the differences between any pair of versions of the marked file, including pairs with the current working copy version of the marked file. +View the differences between any pair of versions of the marked file, including pairs with the current working copy version of the marked file. -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. +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.
-A screenshot of &cervisia;'s browse logs dialogue +A screenshot of &cervisia;'s browse logs dialogue - -A screenshot of &cervisia;'s browse logs dialogue + +A screenshot of &cervisia;'s browse logs dialogue
-You can choose to see the history as provided by the cvs log command (CVS Output), as a Tree, or in List 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 Find... button. - -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 cvs log. 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 CtrlA, CtrlB, respectively. Using the CVS Output view, you can click on the Select for revision A and Select for revision B to mark the revisions. - -If you press the Annotate 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 . - -If you press the Diff button, a cvs diff 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 . - -If you press the Create Patch... 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 OK, a cvs diff command is issued to generate the difference file. A Save As 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 . - -If you press the View button, &cervisia; will retrieve the revision marked as "A" and display it using the default application for its file type. - -Press the Close button to leave the dialogue and return to the main view. - - -To generate the log that is the base for the CVS Log dialogue, &cervisia; issues the following command: +You can choose to see the history as provided by the cvs log command (CVS Output), as a Tree, or in List 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 Find... button. + +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 cvs log. 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 CtrlA, CtrlB, respectively. Using the CVS Output view, you can click on the Select for revision A and Select for revision B to mark the revisions. + +If you press the Annotate 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 . + +If you press the Diff button, a cvs diff 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 . + +If you press the Create Patch... 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 OK, a cvs diff command is issued to generate the difference file. A Save As 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 . + +If you press the View button, &cervisia; will retrieve the revision marked as "A" and display it using the default application for its file type. + +Press the Close button to leave the dialogue and return to the main view. + + +To generate the log that is the base for the CVS Log dialogue, &cervisia; issues the following command: -cvs log file name +cvs log file name -Browsing the History +Browsing the History -If the used repository has logging enabled, &cervisia; can present you a history of certain events like checkouts, commits, rtags, updates and releases. Choose History from the View menu, and &cervisia; will issue the command +If the used repository has logging enabled, &cervisia; can present you a history of certain events like checkouts, commits, rtags, updates and releases. Choose History from the View menu, and &cervisia; will issue the command -cvs history -e -a +cvs history -e -a -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. +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. -Now you can see the list of events, sorted by date. In the second column, the type of the event is shown: +Now you can see the list of events, sorted by date. In the second column, the type of the event is shown: -Checkout - The user who is displayed in the 'Author' column has checked out a module - -Tag - A user has used the command cvs rtag. Note that the usage of cvs tag (as done by &cervisia;'s AdvancedTag/Branch... command) is not recorded in the history database. This has historical reasons (see the &CVS; FAQ). - -Release - A user has released a module. Actually, this command is rarely used and not of much value. - -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. - -Update, Copied - A user has made an update on a file. A new version was copied into working copy. - -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. - -Update, Conflict - A user has made an update on a file, and a conflict with his own modifications was detected. - -Commit, Modified - A user committed a modified file. - -Commit, Added - A user added a file and committed it. - -Commit, Removed - A user removed a file and committed it. +Checkout - The user who is displayed in the 'Author' column has checked out a module + +Tag - A user has used the command cvs rtag. Note that the usage of cvs tag (as done by &cervisia;'s AdvancedTag/Branch... command) is not recorded in the history database. This has historical reasons (see the &CVS; FAQ). + +Release - A user has released a module. Actually, this command is rarely used and not of much value. + +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. + +Update, Copied - A user has made an update on a file. A new version was copied into working copy. + +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. + +Update, Conflict - A user has made an update on a file, and a conflict with his own modifications was detected. + +Commit, Modified - A user committed a modified file. + +Commit, Added - A user added a file and committed it. + +Commit, Removed - A user removed a file and committed it.
-A screenshot of &cervisia;'s history dialogue +A screenshot of &cervisia;'s history dialogue - -A screenshot of &cervisia;'s history dialogue + +A screenshot of &cervisia;'s history dialogue
-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: +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: -Show commit events - shows commits -Show checkout events - shows checkouts -Show tag events - shows taggings -Show other events - shows events not included in the above -Only user - shows only events caused by a certain user -Only file names matching - filters file names by a regular expression -Only dirnames matching - filters folder names by a regular expression +Show commit events - shows commits +Show checkout events - shows checkouts +Show tag events - shows taggings +Show other events - shows events not included in the above +Only user - shows only events caused by a certain user +Only file names matching - filters file names by a regular expression +Only dirnames matching - filters folder names by a regular expression -Special characters recognised by the regular expression matcher are: +Special characters recognised by the regular expression matcher are: -x* matches any number of occurrences of the character x. - -x+ matches one or more of occurrences of the character x. - -x? matches zero or one occurrences of the character x. - -^ matches the start of the string. - -$ matches the end of the string. - -[a-cx-z] matches a set of characters, ⪚ here the set consisting of a,b,c,x,y,z. +x* matches any number of occurrences of the character x. + +x+ matches one or more of occurrences of the character x. + +x? matches zero or one occurrences of the character x. + +^ matches the start of the string. + +$ matches the end of the string. + +[a-cx-z] matches a set of characters, ⪚ here the set consisting of a,b,c,x,y,z. @@ -2088,477 +847,164 @@ Changes in the repository -Advanced Usage +Advanced Usage -Updating to Tag, Branch or Date +Updating to Tag, Branch or Date -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. +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. -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; +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; -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. +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. -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. +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. -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 checkout, to work in parallel with both versions. +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 checkout, to work in parallel with both versions.
-A screenshot of &cervisia;'s update to tag dialogue +A screenshot of &cervisia;'s update to tag dialogue - -A screenshot of &cervisia;'s update to tag dialogue + +A screenshot of &cervisia;'s update to tag dialogue
-Update to branch -Select this option to update to a branch. Enter the name of the branch in the drop down edit box (or press the Fetch List button to retrieve the list of branches from the &CVS; server, and select the one you want in the drop down list). +Update to branch +Select this option to update to a branch. Enter the name of the branch in the drop down edit box (or press the Fetch List button to retrieve the list of branches from the &CVS; server, and select the one you want in the drop down list). -Update to tag -Select this option to update to a tag. Enter the name of the tag in the drop down edit box (or press the Fetch List button to retrieve the list of tags from the &CVS; server, and select the one you want in the drop down list). +Update to tag +Select this option to update to a tag. Enter the name of the tag in the drop down edit box (or press the Fetch List button to retrieve the list of tags from the &CVS; server, and select the one you want in the drop down list). -Update to date -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 yyyy-mm-dd where yyyy is the year, mm is the month (numerically) and dd is the day. Alternatives are some English phrases like yesterday or 2 weeks ago. +Update to date +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 yyyy-mm-dd where yyyy is the year, mm is the month (numerically) and dd is the day. Alternatives are some English phrases like yesterday or 2 weeks ago. -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 AdvancedUpdate to HEAD. - -The comand issued to update to a branch or tag is: cvs update -r tag +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 AdvancedUpdate to HEAD. + +The comand issued to update to a branch or tag is: cvs update -r tag -The command issued to update to a date is: cvs update -D date +The command issued to update to a date is: cvs update -D date -The command issued to update to the main branch (HEAD) is: cvs update +The command issued to update to the main branch (HEAD) is: cvs update -Tagging and Branching - -We discuss here only the technical aspects of tagging and branching. If you are only a user, 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. - -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 CERVISIA_1_0. &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. - -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 AdvancedTag/Branch. Now enter the name of the tag, press Return and you are done. - -Creating a branch is not significantly more difficult: In the tag dialogue, check the box Create branch with this tag. You can also delete an existing tag: Choose AdvancedDelete Tag in the main view. - -Another aspect of branching is the merging of modifications from a branch to the current branch. If you are going to do this, choose AdvancedMerge.... The dialogue that appears now gives you two options: - -Either you may merge all modifications done on a branch to the current branch. In that case, check the box Merge from branch and fill in the branch you want to merge from. &cervisia; will then execute the command +Tagging and Branching + +We discuss here only the technical aspects of tagging and branching. If you are only a user, 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. + +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 CERVISIA_1_0. &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. + +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 AdvancedTag/Branch. Now enter the name of the tag, press Return and you are done. + +Creating a branch is not significantly more difficult: In the tag dialogue, check the box Create branch with this tag. You can also delete an existing tag: Choose AdvancedDelete Tag in the main view. + +Another aspect of branching is the merging of modifications from a branch to the current branch. If you are going to do this, choose AdvancedMerge.... The dialogue that appears now gives you two options: + +Either you may merge all modifications done on a branch to the current branch. In that case, check the box Merge from branch and fill in the branch you want to merge from. &cervisia; will then execute the command -cvs update branchtag +cvs update branchtag -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 Merge modifications and enter (in the correct order) the two relevant tags. This will result in a command +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 Merge modifications and enter (in the correct order) the two relevant tags. This will result in a command -cvs update branchtag1 branchtag2 +cvs update branchtag1 branchtag2 -Using Watches - -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 $CVSROOT/CVSROOT/notify 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. - -&cervisia;'s main support of watches are six menu items. - -In order to add a watch to one or several files, use AdvancedAdd Watch.... 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 Only and Commits. If you want to get notified about any event related to the marked files, check the box All. The command line used when you accept the dialogue is +Using Watches + +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 $CVSROOT/CVSROOT/notify 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. + +&cervisia;'s main support of watches are six menu items. + +In order to add a watch to one or several files, use AdvancedAdd Watch.... 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 Only and Commits. If you want to get notified about any event related to the marked files, check the box All. The command line used when you accept the dialogue is -cvs watch add -a commit file names +cvs watch add -a commit file names -or with a similar option, depending on the events you chose to watch. +or with a similar option, depending on the events you chose to watch. -If you are not interested in some files anymore, you can remove your watches on them. To this end, use AdvancedRemove Watch.... 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 +If you are not interested in some files anymore, you can remove your watches on them. To this end, use AdvancedRemove Watch.... 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 -cvs watch remove file names +cvs watch remove file names -possibly with an option for the chosen events. +possibly with an option for the chosen events. -Finally, you can get a list of the people who are watching a couple of files. Choose AdvancedShow Watchers. Using this menu item will result in a command +Finally, you can get a list of the people who are watching a couple of files. Choose AdvancedShow Watchers. Using this menu item will result in a command -cvs watchers file names +cvs watchers file names -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. +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. -For some developer groups, this is not the preferred model of cooperation. They want to get notified about someone working on a file as soon as 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 AdvancedEdit. This will execute the command +For some developer groups, this is not the preferred model of cooperation. They want to get notified about someone working on a file as soon as 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 AdvancedEdit. This will execute the command -cvs edit file names +cvs edit file names -This will send out a notification to everyone who has set an edit watch on this file. It will also register you as an editor of the file. You can obtain a list of all editors of a certain file by using AdvancedShow Editors. This is equivalent to typing on the command line +This will send out a notification to everyone who has set an edit watch on this file. It will also register you as an editor of the file. You can obtain a list of all editors of a certain file by using AdvancedShow Editors. This is equivalent to typing on the command line -cvs editors file names +cvs editors file names -An editing session is automatically ended when you commit the affected file. At that moment, an unedit 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 AdvancedUnedit. Note that &cervisia; will not ask you for confirmation; that means if you use this menu item, all your work done since you used AdvancedEdit will be lost. Precisely, &cervisia; uses the command line +An editing session is automatically ended when you commit the affected file. At that moment, an unedit 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 AdvancedUnedit. Note that &cervisia; will not ask you for confirmation; that means if you use this menu item, all your work done since you used AdvancedEdit will be lost. Precisely, &cervisia; uses the command line -echo y | cvs unedit file names +echo y | cvs unedit file names -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 enforces the usage of these commands. The responsible command to switch to this model is cvs watch on 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 readonly. That means you cannot edit a file by default (unless you use tricks like chmod). Only when you use AdvancedEdit, the file becomes writable. It is made read-only again when you commit the file or use AdvancedUnedit. - -&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 FileEdit, 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 cvs edit before, so that all people watching the file get a notification that you are working on it. - -In such a case, it is advisable to check the option SettingsDo cvs edit Automatically When Necessary. Now, whenever you edit a file by double-clicking it, &cervisia; will run cvs edit 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. +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 enforces the usage of these commands. The responsible command to switch to this model is cvs watch on 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 readonly. That means you cannot edit a file by default (unless you use tricks like chmod). Only when you use AdvancedEdit, the file becomes writable. It is made read-only again when you commit the file or use AdvancedUnedit. + +&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 FileEdit, 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 cvs edit before, so that all people watching the file get a notification that you are working on it. + +In such a case, it is advisable to check the option SettingsDo cvs edit Automatically When Necessary. Now, whenever you edit a file by double-clicking it, &cervisia; will run cvs edit 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. -Locking - -The development model usually followed when &CVS; is used is called unreserved checkouts. Each developer has his own sandbox where he can edit files as he likes. If when the watch features - like cvs edit - 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. - -Other revision control systems - like RCS and SourceSafe use a different model. When a developer wants to a edit a file, he has to lock 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. - -With &cervisia;, you lock files as follows. Select the desired files in the main view. Then choose AdvancedLock. This runs the command +Locking + +The development model usually followed when &CVS; is used is called unreserved checkouts. Each developer has his own sandbox where he can edit files as he likes. If when the watch features - like cvs edit - 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. + +Other revision control systems - like RCS and SourceSafe use a different model. When a developer wants to a edit a file, he has to lock 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. + +With &cervisia;, you lock files as follows. Select the desired files in the main view. Then choose AdvancedLock. This runs the command -cvs admin -l file names +cvs admin -l file names -The reverse effect is achieved by using AdvancedUnlock. This runs the command +The reverse effect is achieved by using AdvancedUnlock. This runs the command -cvs admin -u file names +cvs admin -u file names @@ -2567,57 +1013,24 @@ Changes in the repository -Customising &cervisia; +Customising &cervisia; -&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 Settings menu. Others are united in a common dialogue which is available via OptionSettings.... +&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 Settings menu. Others are united in a common dialogue which is available via OptionSettings.... -General +General -User name for the ChangeLog editor: -Whenever you use the menu item FileInsert ChangeLog Entry..., 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. +User name for the ChangeLog editor: +Whenever you use the menu item FileInsert ChangeLog Entry..., 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. -Path to cvs executable, or 'cvs': -Here you can set the name (or path) to the cvs command line client. By default, the &CVS; executable found in your $PATH is used by &cervisia;. +Path to cvs executable, or 'cvs': +Here you can set the name (or path) to the cvs command line client. By default, the &CVS; executable found in your $PATH is used by &cervisia;. @@ -2625,81 +1038,28 @@ Changes in the repository -Diff Viewer +Diff Viewer -Number of context lines in the diff dialogue: -For the diff dialogue, &cervisia; uses the option to diff. This lets diff show only a limited number of lines around each difference region (context lines). Here you can set the argument to . +Number of context lines in the diff dialogue: +For the diff dialogue, &cervisia; uses the option to diff. This lets diff show only a limited number of lines around each difference region (context lines). Here you can set the argument to . -Additional options for cvs diff: -Here you can add additional arguments to the diff. A popular example is which lets diff ignore changes in the amount of whitespace. +Additional options for cvs diff: +Here you can add additional arguments to the diff. A popular example is which lets diff ignore changes in the amount of whitespace. -Tab width in diff dialogue: -In the diff dialogue, tab characters present in your file or in the output of the diff 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. +Tab width in diff dialogue: +In the diff dialogue, tab characters present in your file or in the output of the diff 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. -External diff frontend: -When you use any of the features which show the diff dialogue, like ViewDifference to Repository..., &cervisia; invokes its internal diff frontend. If you prefer a different one, like Kompare, TkDiff or xxdiff, enter its file name and path here. +External diff frontend: +When you use any of the features which show the diff dialogue, like ViewDifference to Repository..., &cervisia; invokes its internal diff frontend. If you prefer a different one, like Kompare, TkDiff or xxdiff, enter its file name and path here. @@ -2707,43 +1067,18 @@ Changes in the repository -Status +Status -When opening a sandbox from a remote repository, start a File->Status command automatically -When you check this option, the FileStatus 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). +When opening a sandbox from a remote repository, start a File->Status command automatically +When you check this option, the FileStatus 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). -When opening a sandbox from a local repository, start a File->Status command automatically -When you check this option, the FileStatus command is started whenever you open a local sandbox. +When opening a sandbox from a local repository, start a File->Status command automatically +When you check this option, the FileStatus command is started whenever you open a local sandbox. @@ -2751,62 +1086,23 @@ Changes in the repository -Advanced +Advanced -Timeout after which a progress dialogue appears (in ms): -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 ViewDifference to Repository... &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. +Timeout after which a progress dialogue appears (in ms): +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 ViewDifference to Repository... &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. -Default compression level: -The cvs client compresses files and patches when they are transferred over a network. With the command line 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 RepositoryRepositories.... +Default compression level: +The cvs client compresses files and patches when they are transferred over a network. With the command line 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 RepositoryRepositories.... -Utilise a running or start a new ssh-agent process -Check this box if you use ext (rsh) repositories, the &ssh; remote shell to communicate with the repository and ssh-agent to manage your keys. +Utilise a running or start a new ssh-agent process +Check this box if you use ext (rsh) repositories, the &ssh; remote shell to communicate with the repository and ssh-agent to manage your keys. @@ -2815,90 +1111,33 @@ Changes in the repository -Look'n'feel +Look'n'feel -Font for protocol window... -Press this button to open the Set Font dialogue, to set the font used in the protocol window (this is the window showing the output of the cvs client). +Font for protocol window... +Press this button to open the Set Font dialogue, to set the font used in the protocol window (this is the window showing the output of the cvs client). -Font for annotate view... -Press this button to open the Set Font dialogue, to set the font used in the annotate view. +Font for annotate view... +Press this button to open the Set Font dialogue, to set the font used in the annotate view. -Font for diff view... -Press this button to open the Set Font dialogue, to set the font used in diff dialogs. +Font for diff view... +Press this button to open the Set Font dialogue, to set the font used in diff dialogs. -Colours -Press the coloured buttons to open the Select Colour dialogue, to set the colour used for Conflict, Local Change or Remote Change, in the main view or Diff change, Diff insertion or Diff deletion, in &cervisia;'s built-in diff frontend. +Colours +Press the coloured buttons to open the Select Colour dialogue, to set the colour used for Conflict, Local Change or Remote Change, in the main view or Diff change, Diff insertion or Diff deletion, in &cervisia;'s built-in diff frontend. -Split main window horizontally -&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. +Split main window horizontally +&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. @@ -2908,123 +1147,44 @@ Changes in the repository -Appendix +Appendix -Ignored Files +Ignored Files -In its main file tree, &cervisia; does not display all files which are actually there. This is analogue to cvs itself and helps to avoid clutter caused by uninteresting stuff like object files. &cervisia; tries to mimic cvs's behavior as close as possible, i.e. it gets ignore lists from the following sources: +In its main file tree, &cervisia; does not display all files which are actually there. This is analogue to cvs itself and helps to avoid clutter caused by uninteresting stuff like object files. &cervisia; tries to mimic cvs's behavior as close as possible, i.e. it gets ignore lists from the following sources: -A static list of entries which includes things like *.o and core. For details, see the &CVS; documentation. -The file $HOME/.cvsignore. - -The environment variable $CVSIGNORE. -The .cvsignore file in the respective folder. +A static list of entries which includes things like *.o and core. For details, see the &CVS; documentation. +The file $HOME/.cvsignore. + +The environment variable $CVSIGNORE. +The .cvsignore file in the respective folder. -cvs itself additionally looks up entries in $CVSROOT/CVSROOT/cvsignore, 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 .cvsignore file in your home folder. +cvs itself additionally looks up entries in $CVSROOT/CVSROOT/cvsignore, 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 .cvsignore file in your home folder. -Further Information and Support +Further Information and Support -&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 info:/cvs into the locationbar of kdehelp, khelpcenter resp. Alternative, you can just choose HelpCVS Info in &cervisia;. An on-line HTML version of the Cederqvist is available on the web. - -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. - -Karl Fogel has written the excellent book Open Source Development with CVS. 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. - -&CVS; issues are discussed on a dedicated mailing list. - -There is USENET group comp.software.config-mgmt 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;. - -Last but not least, there is a (low traffic) &cervisia; mailing list. +&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 info:/cvs into the locationbar of kdehelp, khelpcenter resp. Alternative, you can just choose HelpCVS Info in &cervisia;. An on-line HTML version of the Cederqvist is available on the web. + +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. + +Karl Fogel has written the excellent book Open Source Development with CVS. 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. + +&CVS; issues are discussed on a dedicated mailing list. + +There is USENET group comp.software.config-mgmt 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;. + +Last but not least, there is a (low traffic) &cervisia; mailing list. @@ -3032,252 +1192,80 @@ Changes in the repository -Command Reference +Command Reference -The File Menu +The File Menu -FileOpen Sandbox... -Opens a sandbox in the main window. See . +FileOpen Sandbox... +Opens a sandbox in the main window. See . -FileRecent sandboxes -Opens one of the sandboxes that were in use recently. +FileRecent sandboxes +Opens one of the sandboxes that were in use recently. -FileInsert ChangeLog Entry... -Opens the ChangeLog editor, prepared such that you can add a new entry with the current date. See . +FileInsert ChangeLog Entry... +Opens the ChangeLog editor, prepared such that you can add a new entry with the current date. See . -&Ctrl;U FileUpdate -Runs 'cvs update' on selected files and changes the status and revision numbers in the listing accordingly. See . +&Ctrl;U FileUpdate +Runs 'cvs update' on selected files and changes the status and revision numbers in the listing accordingly. See . -F5 FileStatus -Runs 'cvs -n update' on selected files and changes the status and revision numbers in the listing accordingly. See . +F5 FileStatus +Runs 'cvs -n update' on selected files and changes the status and revision numbers in the listing accordingly. See . -FileEdit -Opens the selected file in KDE's default editor for the selected file's type. +FileEdit +Opens the selected file in KDE's default editor for the selected file's type. -FileResolve... -Opens a dialogue for the selected file which allows you to resolve merge conflicts in it. See . +FileResolve... +Opens a dialogue for the selected file which allows you to resolve merge conflicts in it. See . -# FileCommit... -Allows you to commit the selected files. See . +# FileCommit... +Allows you to commit the selected files. See . -+ FileAdd to Repository... -Allows you to add the selected files to the repository. See . ++ FileAdd to Repository... +Allows you to add the selected files to the repository. See . -FileAdd Binary... -Allows you to add the selected files to the repository as binaries (cvs add). See . +FileAdd Binary... +Allows you to add the selected files to the repository as binaries (cvs add). See . -- FileRemove from Repository... -Allows you to remove the selected files from the repository. See . +- FileRemove from Repository... +Allows you to remove the selected files from the repository. See . -FileRevert -Discards any local changes you have made to the selected files and reverts to the version in the repository (Option to cvs update). +FileRevert +Discards any local changes you have made to the selected files and reverts to the version in the repository (Option to cvs update). -&Ctrl;Q FileExit -Quits &cervisia;. +&Ctrl;Q FileExit +Quits &cervisia;. @@ -3287,258 +1275,81 @@ Changes in the repository -The View Menu +The View Menu -Escape ViewStop -Aborts any running subprocesses. +Escape ViewStop +Aborts any running subprocesses. -&Ctrl;L ViewBrowse Log... -Shows the log browser of the selected file versions. See . +&Ctrl;L ViewBrowse Log... +Shows the log browser of the selected file versions. See . -&Ctrl;A ViewAnnotate... -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 . +&Ctrl;A ViewAnnotate... +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 . -&Ctrl;D ViewDifference to Repository (BASE)... -Shows the differences between the selected file in the sandbox and the revision you last updated (BASE). See . +&Ctrl;D ViewDifference to Repository (BASE)... +Shows the differences between the selected file in the sandbox and the revision you last updated (BASE). See . -&Ctrl;H ViewDifference to Repository (HEAD)... -Shows the differences between the selected file in the sandbox and the revision you last updated (HEAD). See . +&Ctrl;H ViewDifference to Repository (HEAD)... +Shows the differences between the selected file in the sandbox and the revision you last updated (HEAD). See . -ViewLast Change... -Shows the differences between the revision of the selected file you last updated (BASE) and the revision before. See . +ViewLast Change... +Shows the differences between the revision of the selected file you last updated (BASE) and the revision before. See . -ViewHistory... -Shows the &CVS; history as reported by the server. See . +ViewHistory... +Shows the &CVS; history as reported by the server. See . -ViewHide All Files -Determines whether only folders are shown in the main tree view. See . +ViewHide All Files +Determines whether only folders are shown in the main tree view. See . -ViewHide Unmodified Files -Determines whether unknown and up to date files are hidden in the main tree view. See . +ViewHide Unmodified Files +Determines whether unknown and up to date files are hidden in the main tree view. See . -ViewHide Removed Files -Determines whether removed files are hidden in the main tree view. See . +ViewHide Removed Files +Determines whether removed files are hidden in the main tree view. See . -ViewHide Non-CVS Files -Determines whether files not in CVS are hidden in the main tree view. See . +ViewHide Non-CVS Files +Determines whether files not in CVS are hidden in the main tree view. See . -ViewHide Empty Folders -Determines whether without visible entries are hidden in the main tree view. See . +ViewHide Empty Folders +Determines whether without visible entries are hidden in the main tree view. See . -ViewUnfold File Tree -Opens all branches in the file tree so that you can see all files and folders. See . +ViewUnfold File Tree +Opens all branches in the file tree so that you can see all files and folders. See . -ViewFold File Tree -Closes all branches in the file tree. See . +ViewFold File Tree +Closes all branches in the file tree. See . @@ -3548,224 +1359,77 @@ Changes in the repository -The Advanced Menu +The Advanced Menu -AdvancedTag/Branch... -Tags or branches the selected files. See . +AdvancedTag/Branch... +Tags or branches the selected files. See . -AdvancedDelete Tag... -Removes a given tag from the selected files. See . +AdvancedDelete Tag... +Removes a given tag from the selected files. See . -AdvancedUpdate to Tag/Date... -Brings the selected files to a given tag or date, making it sticky. See . +AdvancedUpdate to Tag/Date... +Brings the selected files to a given tag or date, making it sticky. See . -AdvancedUpdate to HEAD... -Brings the selected files to the respective HEAD revision. See . +AdvancedUpdate to HEAD... +Brings the selected files to the respective HEAD revision. See . -AdvancedMerge... -Merges either a given branch or the modifications between two tags into the selected files. See . +AdvancedMerge... +Merges either a given branch or the modifications between two tags into the selected files. See . -AdvancedAdd Watch... -Adds a watch for a set of events on the selected files. See . +AdvancedAdd Watch... +Adds a watch for a set of events on the selected files. See . -AdvancedRemove Watch... -Removes a watch for a set of events from the selected files. See . +AdvancedRemove Watch... +Removes a watch for a set of events from the selected files. See . -AdvancedShow Watchers -Lists the watchers of the selected files. See . +AdvancedShow Watchers +Lists the watchers of the selected files. See . -AdvancedEdit -Runs cvs edit on the selected files. See . +AdvancedEdit +Runs cvs edit on the selected files. See . -AdvancedUnedit -Runs cvs unedit on the selected files. See . +AdvancedUnedit +Runs cvs unedit on the selected files. See . -AdvancedShow Editors -Runs cvs editors on the selected files. See . +AdvancedShow Editors +Runs cvs editors on the selected files. See . -AdvancedLock -Locks the selected files. See . +AdvancedLock +Locks the selected files. See . -AdvancedUnlock -Unlocks the selected files. See . +AdvancedUnlock +Unlocks the selected files. See . -AdvancedCreate Patch Against Repository... -Creates a patch from the modifications in your sandbox. See . +AdvancedCreate Patch Against Repository... +Creates a patch from the modifications in your sandbox. See . @@ -3775,69 +1439,28 @@ Changes in the repository -The Repository Menu +The Repository Menu -RepositoryCreate... -Opens a dialogue which allows you to create a new local repository. See . +RepositoryCreate... +Opens a dialogue which allows you to create a new local repository. See . -RepositoryCheckout... -Opens a dialogue which allows you to checkout a module from a repository. See . +RepositoryCheckout... +Opens a dialogue which allows you to checkout a module from a repository. See . -RepositoryImport... -Opens a dialogue which allows you to import a package into the repository. See . +RepositoryImport... +Opens a dialogue which allows you to import a package into the repository. See . -RepositoryRepositories... -Configures a list of repositories you often use and how to access them. See . +RepositoryRepositories... +Configures a list of repositories you often use and how to access them. See . @@ -3846,164 +1469,53 @@ Changes in the repository -The Settings Menu +The Settings Menu -SettingsShow Toolbar -Determines whether the toolbar is displayed. +SettingsShow Toolbar +Determines whether the toolbar is displayed. -SettingsCreate Folders on Update -Determines whether updates create folders in the sandbox which were not there before (Option to cvs update). +SettingsCreate Folders on Update +Determines whether updates create folders in the sandbox which were not there before (Option to cvs update). -SettingsPrune Empty Folders on Update -Determines whether updates remove empty folders in the sandbox. (Option to cvs update). +SettingsPrune Empty Folders on Update +Determines whether updates remove empty folders in the sandbox. (Option to cvs update). -SettingsUpdate Recursively -Determines whether updates are recursive (Option to cvs update). +SettingsUpdate Recursively +Determines whether updates are recursive (Option to cvs update). -SettingsCommit and Remove Recursively -Determines whether commits and removes are recursive (Option to cvs add, cvs remove resp.). +SettingsCommit and Remove Recursively +Determines whether commits and removes are recursive (Option to cvs add, cvs remove resp.). -SettingsDo cvs edit Automatically When Necessary -Determines whether cvs edit is executed automatically whenever you edit a file. +SettingsDo cvs edit Automatically When Necessary +Determines whether cvs edit is executed automatically whenever you edit a file. -SettingsConfigure Shortcuts... -Opens a dialogue for configuring keybindings. +SettingsConfigure Shortcuts... +Opens a dialogue for configuring keybindings. -SettingsConfigure Toolbars... -Opens a dialogue for configuring &cervisia;'s toolbars. +SettingsConfigure Toolbars... +Opens a dialogue for configuring &cervisia;'s toolbars. -SettingsConfigure Cervisia... -Opens a dialogue for customising &cervisia;. +SettingsConfigure Cervisia... +Opens a dialogue for customising &cervisia;. @@ -4012,88 +1524,33 @@ Changes in the repository -The Help Menu +The Help Menu -F1 HelpHandbook -Invokes the KDE Help system starting at the &cervisia; help pages. (this document). +F1 HelpHandbook +Invokes the KDE Help system starting at the &cervisia; help pages. (this document). -HelpReport Bug... -Opens the Bug report dialogue. +HelpReport Bug... +Opens the Bug report dialogue. -Help About &cervisia; -This will display version and author information. +Help About &cervisia; +This will display version and author information. -HelpAbout KDE -This displays the KDE version and other basic information. +HelpAbout KDE +This displays the KDE version and other basic information. -HelpCVS Manual -Opens the &CVS; info pages in the KDE help system. +HelpCVS Manual +Opens the &CVS; info pages in the KDE help system. @@ -4106,7 +1563,6 @@ Changes in the repository -Credits And Licenses +Credits And Licenses &underFDL; 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 @@ + --> @@ -11,57 +10,27 @@ - + -MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English +MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English -Using &cataloguemanager; +Using &cataloguemanager; -Screenshot of &cataloguemanager; +Screenshot of &cataloguemanager; -Screenshot of &cataloguemanager; +Screenshot of &cataloguemanager; -The Catalogue Manager merges two folders into one tree and displays all the PO and POT 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. -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: +The Catalogue Manager merges two folders into one tree and displays all the PO and POT 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. +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: @@ -70,8 +39,7 @@ - All the messages in this file are translated. + All the messages in this file are translated. @@ -79,8 +47,7 @@ - Some of the messages in this file are fuzzy or untranslated + Some of the messages in this file are fuzzy or untranslated @@ -88,10 +55,7 @@ - This file does not exist in the folder of the PO files. + This file does not exist in the folder of the PO files. @@ -99,8 +63,7 @@ - This file contains syntax errors. + This file contains syntax errors. @@ -108,106 +71,43 @@ - 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. + 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. -If an icon is marked with this icon , like , it indicates that this file or folder does not exist in the folder of the POT files. - -You can mark or unmark a file by selecting Toggle Marking in the context menu of a file. - -If you want to toggle or remove all markings in a folder, press the right mouse button over the folder and select Toggle Markings or Remove Markings. The markings are automatically saved when leaving &kbabel;. - -To open a file either double-click on the file, select Open from the context menu or press either Return or &Ctrl;O . - -You can configure the &cataloguemanager; by Settings Configure &cataloguemanager;.... See section Preferences for more details. +If an icon is marked with this icon , like , it indicates that this file or folder does not exist in the folder of the POT files. + +You can mark or unmark a file by selecting Toggle Marking in the context menu of a file. + +If you want to toggle or remove all markings in a folder, press the right mouse button over the folder and select Toggle Markings or Remove Markings. The markings are automatically saved when leaving &kbabel;. + +To open a file either double-click on the file, select Open from the context menu or press either Return or &Ctrl;O . + +You can configure the &cataloguemanager; by Settings Configure &cataloguemanager;.... See section Preferences for more details. -&cataloguemanager; Features -Besides the main feature for opening the files in &kbabel; &cataloguemanager; supports number of other features for maintaining a tree of PO-files. +&cataloguemanager; Features +Besides the main feature for opening the files in &kbabel; &cataloguemanager; supports number of other features for maintaining a tree of PO-files. -Find and replace in multiple files -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; +Find and replace in multiple files +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; -Statistics -&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. +Statistics +&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. -Checking the syntax -This allows you to check the syntax of multiple PO-files using msgfmt. If a file fails this check, it cannot be used for generating a MO-file for binary distribution. Such an incorrect file will typically result in failing compilation of the package the PO-file belongs to. +Checking the syntax +This allows you to check the syntax of multiple PO-files using msgfmt. If a file fails this check, it cannot be used for generating a MO-file for binary distribution. Such an incorrect file will typically result in failing compilation of the package the PO-file belongs to. -User-defined commands -Because &cataloguemanager; cannot provide any functionality you would like to use, you can extend it by defining your own commands. -There are two sets of commands. One for folders and one for single files. You can set them in configuration dialogue and access by pressing &RMB; on an entry in the file list. +User-defined commands +Because &cataloguemanager; cannot provide any functionality you would like to use, you can extend it by defining your own commands. +There are two sets of commands. One for folders and one for single files. You can set them in configuration dialogue and access by pressing &RMB; on an entry in the file list. 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 @@ + --> @@ -11,615 +10,284 @@ - + -MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English +MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English -Dictionaries +Dictionaries -&kbabel; has 3 modes which can be used to search translated PO message strings: +&kbabel; has 3 modes which can be used to search translated PO message strings: - Searching translation, using a translation database + Searching translation, using a translation database - Rough translation + Rough translation - &kbabeldict; + &kbabeldict; -Translation database +Translation database -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. +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. -This mode is the one best integrated with &kbabel;. Besides searching and rough translation it also supports the following features: +This mode is the one best integrated with &kbabel;. Besides searching and rough translation it also supports the following features: -Every new translation typed in the &kbabel; editor can be automatically stored in the database. +Every new translation typed in the &kbabel; editor can be automatically stored in the database. -This database can be used for diff-ing msgid. +This database can be used for diff-ing msgid. -Of course, the more translations are stored in the database, the more productive you can be. To fill the database, you can use the Database tab in the preferences dialogue or you can turn on automatic addition of every translated messages on the same tab. +Of course, the more translations are stored in the database, the more productive you can be. To fill the database, you can use the Database tab in the preferences dialogue or you can turn on automatic addition of every translated messages on the same tab. -Settings -You can configure this searching mode and how it should be used by selecting Settings Configure Dictionary Translation Database in &kbabel; menu. -The Generic tab contains general settings for searching in the database. +Settings +You can configure this searching mode and how it should be used by selecting Settings Configure Dictionary Translation Database in &kbabel; menu. +The Generic tab contains general settings for searching in the database. - Search in whole database (slow) + Search in whole database (slow) - Do not use good keys, search in the whole database. This is slow, but will return the most precise results. + Do not use good keys, search in the whole database. This is slow, but will return the most precise results. - Search in list of "good keys" (best) + Search in list of "good keys" (best) - Use good keys strategy. This option will give you the best tradeoff between speed and exact matching. + Use good keys strategy. This option will give you the best tradeoff between speed and exact matching. - Return the list of "good keys" (fast) + Return the list of "good keys" (fast) - Just return good keys, 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. + Just return good keys, 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. - Case sensitive + Case sensitive - Distinguish case of letters when searching the text. + Distinguish case of letters when searching the text. - Normalise white space + Normalise white space - Skip unnecessary white space in the texts, so the searching will ignore small differences of white space, ⪚ number of spaces in the text. + Skip unnecessary white space in the texts, so the searching will ignore small differences of white space, ⪚ number of spaces in the text. - Remove context comment + Remove context comment - Do not include context comments in search. You will want this to be turned on. + Do not include context comments in search. You will want this to be turned on. - Character to be ignored + Character to be ignored - Here you can enter characters, which should be ignored while searching. Typical example would be accelerator mark, &ie; & for &kde; texts. + Here you can enter characters, which should be ignored while searching. Typical example would be accelerator mark, &ie; & for &kde; texts. -The Search 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 Word substitution. By substituting one or two words the approximate text can be found as well. For example, assume you are trying to find the text My name is Andrea. +The Search 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 Word substitution. By substituting one or two words the approximate text can be found as well. For example, assume you are trying to find the text My name is Andrea. - Equal + Equal - Text from database matches if it is the same as the searched string. In our example it can be My name is &Andrea (if & is set as ignored character in Characters to be ignored on Generic tab). + Text from database matches if it is the same as the searched string. In our example it can be My name is &Andrea (if & is set as ignored character in Characters to be ignored on Generic tab). - Query is contained + Query is contained - Text from database matches if the searched string is contained in it. For our example it can be My name is Andrea, you know?. + Text from database matches if the searched string is contained in it. For our example it can be My name is Andrea, you know?. - Query contains + Query contains - Text from database matches if the searched string contains it. For our example it can be Andrea. You can use this for enumerating the possibilities to be found. + Text from database matches if the searched string contains it. For our example it can be Andrea. You can use this for enumerating the possibilities to be found. - Regular Expression + Regular Expression - Consider searched text as a regular expression. This is mainly used for &kbabeldict;. You can hardly expect regular expressions in PO files. + Consider searched text as a regular expression. This is mainly used for &kbabeldict;. You can hardly expect regular expressions in PO files. - Use one word substitution + Use one word substitution - 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 Your name is Andrea as well. + 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 Your name is Andrea as well. - Max number of words in the query + Max number of words in the query - Maximal number of words in a query to enable one word substitution. + Maximal number of words in a query to enable one word substitution. - Local characters for regular expressions + Local characters for regular expressions - Characters to be considered part of regular expressions. + Characters to be considered part of regular expressions. -Two-word substitution is not implemented yet. +Two-word substitution is not implemented yet. -Filling the database -The Database tab allows to define where is the database stored on disk (Database folder) and if it should be used for automatic storing of the new translations (Auto add entry to database). In this case you should specify the author of the new translation in Auto added entry author. -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 Repeated strings 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. +Filling the database +The Database tab allows to define where is the database stored on disk (Database folder) and if it should be used for automatic storing of the new translations (Auto add entry to database). In this case you should specify the author of the new translation in Auto added entry author. +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 Repeated strings 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. -Filling the database +Filling the database -Filling the database by existing PO-files +Filling the database by existing PO-files - + -Defining good keys -On the Good keys tab are the thresholds to specify how to fill the list of good keys. Minimum number of query words in the key (%) 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 Minimum number of words of the key also in the query (%). The length of the words can be set by Max length spinbox. -Searched text typically contains number of generic words, ⪚ articles. You can eliminate the words based on the frequency. You can discard them by Discard words more frequent than or consider as always present by frequent words are considered as in every key. This way the frequent words will be almost invisible for queries. +Defining good keys +On the Good keys tab are the thresholds to specify how to fill the list of good keys. Minimum number of query words in the key (%) 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 Minimum number of words of the key also in the query (%). The length of the words can be set by Max length spinbox. +Searched text typically contains number of generic words, ⪚ articles. You can eliminate the words based on the frequency. You can discard them by Discard words more frequent than or consider as always present by frequent words are considered as in every key. This way the frequent words will be almost invisible for queries. -Auxiliary PO file - -This searching mode is based on matching the same original English string (the msgid) translated in some other language in an auxillary PO file. It is very common for romanic languages to have similar words, similarly for anglosaxon and slavonic ones. - -For example, say I wanted to translate the word on, from tdelibs.po, into Romanian but have no idea. I look in the same file for French and find actif, and in the Spanish one find activado. So, I conclude that the best one in Romanian will be active. &kbabel; automates this task. Currently you can define only one auxiliary file to search. +Auxiliary PO file + +This searching mode is based on matching the same original English string (the msgid) translated in some other language in an auxillary PO file. It is very common for romanic languages to have similar words, similarly for anglosaxon and slavonic ones. + +For example, say I wanted to translate the word on, from tdelibs.po, into Romanian but have no idea. I look in the same file for French and find actif, and in the Spanish one find activado. So, I conclude that the best one in Romanian will be active. &kbabel; automates this task. Currently you can define only one auxiliary file to search. -Settings -You can configure this searching mode by selecting Settings Configure Dictionary PO Auxiliary from the &kbabel; menu. - -In the Configure Dictionary PO Auxiliary dialogue you can select the path to the auxiliary PO file. To automate PO-file switching when you change current edited file there are many variables delimited by @ char that are replaced by appropriate values: +Settings +You can configure this searching mode by selecting Settings Configure Dictionary PO Auxiliary from the &kbabel; menu. + +In the Configure Dictionary PO Auxiliary dialogue you can select the path to the auxiliary PO file. To automate PO-file switching when you change current edited file there are many variables delimited by @ char that are replaced by appropriate values: - @PACKAGE@ - The name of application or package currently being translated. For example, it can expand to kbabel, tdelibs, konqueror and so on. + @PACKAGE@ + The name of application or package currently being translated. For example, it can expand to kbabel, tdelibs, konqueror and so on. - @LANG@ - The language code. For example can expand to: en_GB, de, ro, fr etc. + @LANG@ + The language code. For example can expand to: en_GB, de, ro, fr etc. - @DIRn@ - where n is a positive integer. This expands to the n-th folder counted from the filename (right to left). + @DIRn@ + where n is a positive integer. This expands to the n-th folder counted from the filename (right to left). -The edit line displays the actual path to the auxiliary PO 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 PO file. Let's take an example. - -I'm Romanian and I have some knowledge about French language and I work on &kde; translation. - -First step is to download a very fresh tde-i18n-fr.tar.bz2 from the &kde; &FTP; site or to use the CVS system to put on my hard-disk a French translation tree. I do this into /home/clau/cvs-cvs.kde.org/tde-i18n/fr. - -My PO sources folder is in /home/clau/cvs-cvs.kde.org/tde-i18n/ro. Don't forget to select PO Auxiliary as the default dictionary and check Automatically start search on the Search tab from &kbabel;'s Preferences dialogue. +The edit line displays the actual path to the auxiliary PO 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 PO file. Let's take an example. + +I'm Romanian and I have some knowledge about French language and I work on &kde; translation. + +First step is to download a very fresh tde-i18n-fr.tar.bz2 from the &kde; &FTP; site or to use the CVS system to put on my hard-disk a French translation tree. I do this into /home/clau/cvs-cvs.kde.org/tde-i18n/fr. + +My PO sources folder is in /home/clau/cvs-cvs.kde.org/tde-i18n/ro. Don't forget to select PO Auxiliary as the default dictionary and check Automatically start search on the Search tab from &kbabel;'s Preferences dialogue. -PO compendium - -A compendium is a file containing a collection of all translation messages (pairs of msgid and msgstr) in a project, ⪚ in &kde;. Typically, compendium for a given language is created by concatenating all PO files of the project for the language. Compendium can contain translated, untranslated and fuzzy messages. Untranslated ones are ignored by this module. - -Similarly to Auxiliary PO, this searching mode is based on matching the same original string (msgid) in a compendium. Currently you can define only one compendium file to search. - -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. +PO compendium + +A compendium is a file containing a collection of all translation messages (pairs of msgid and msgstr) in a project, ⪚ in &kde;. Typically, compendium for a given language is created by concatenating all PO files of the project for the language. Compendium can contain translated, untranslated and fuzzy messages. Untranslated ones are ignored by this module. + +Similarly to Auxiliary PO, this searching mode is based on matching the same original string (msgid) in a compendium. Currently you can define only one compendium file to search. + +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. -Settings - -You can configure this searching mode by selecting Settings Configure Dictionary PO Compendium in &kbabel;'s menu. - -In Configure Dictionary PO Compendium 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 @ char which si replaced by appropriate value: +Settings + +You can configure this searching mode by selecting Settings Configure Dictionary PO Compendium in &kbabel;'s menu. + +In Configure Dictionary PO Compendium 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 @ char which si replaced by appropriate value: - @LANG@ - The language code. For example can expand to: en_GB, de, ro, fr etc. + @LANG@ + The language code. For example can expand to: en_GB, de, ro, fr etc. -In the edit line is displayed the actual path to compendium PO file. While you had best use provided variables in path, it's possible to choose an absolute, real path to an existing PO file to be used as a compendium. +In the edit line is displayed the actual path to compendium PO file. While you had best use provided variables in path, it's possible to choose an absolute, real path to an existing PO file to be used as a compendium. -A very fresh compendium for &kde; translation into ⪚ French you can download fr.messages.bz2 from the &kde; &FTP; site. +A very fresh compendium for &kde; translation into ⪚ French you can download fr.messages.bz2 from the &kde; &FTP; site. -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. +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. - Case sensitive + Case sensitive - If the matching of message in compendium should distinguish between uppercase and lowercase letters. + If the matching of message in compendium should distinguish between uppercase and lowercase letters. - Ignore fuzzy string + Ignore fuzzy string - 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 PO files of the project which can include fuzzy messages. Untranslated ones are ignored always (You can't search for translation in untranslated messages, right?) + 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 PO files of the project which can include fuzzy messages. Untranslated ones are ignored always (You can't search for translation in untranslated messages, right?) - Only whole words + Only whole words - If the matching text should start and end at the boundaries of words. + If the matching text should start and end at the boundaries of words. - A text matches if it is equal to search text + A text matches if it is equal to search text - A text in compendium matches the search text only if it is exactly the same (of course using the options above). + A text in compendium matches the search text only if it is exactly the same (of course using the options above). - A text matches if it is similar to search text + A text matches if it is similar to search text - A text in compendium matches the search text only if it is similar. Both texts are compared by short chunks of letters (3-grams) and at least half of the chunks has to be same. + A text in compendium matches the search text only if it is similar. Both texts are compared by short chunks of letters (3-grams) and at least half of the chunks has to be same. - A text matches if it contains search text + A text matches if it contains search text - A text in compendium matches the search text if it contains the search text. + A text in compendium matches the search text if it contains the search text. - A text matches if it is contained in search text + A text matches if it is contained in search text - A text in compendium matches the search text if it is contained the search text. + A text in compendium matches the search text if it is contained the search text. - A text matches if it contains a word of search text + A text matches if it contains a word of search text - 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. + 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. 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 @@ + --> @@ -10,85 +9,31 @@ - + -MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English +MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English -Questions and Answers +Questions and Answers - Why does &kbabel; show question marks when entering language specific characters? + Why does &kbabel; show question marks when entering language specific characters? - This is a problem with your locale settings. The following might help: Exit &kbabel;, in a shell set the environment variable LANG to a locale, valid for your language. If you use bash do export LANG=change this. For example, when you use german characters, do export LANG=de_DE.88591. Then start &kbabel; from this shell. If the problem is gone, insert this command in your ~/.profile. + This is a problem with your locale settings. The following might help: Exit &kbabel;, in a shell set the environment variable LANG to a locale, valid for your language. If you use bash do export LANG=change this. For example, when you use german characters, do export LANG=de_DE.88591. Then start &kbabel; from this shell. If the problem is gone, insert this command in your ~/.profile. - Why does &kbabel; show question marks instead of language specific characters after loading a PO file? + Why does &kbabel; show question marks instead of language specific characters after loading a PO file? - 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 &Ctrl;F to find all the corrupted characters and replace them. Do not search for real question marks, because these characters are only displayed as question marks, but internally they are different characters. Otherwise you might want to install an Unicode font, which contains all necessary characters. + 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 &Ctrl;F to find all the corrupted characters and replace them. Do not search for real question marks, because these characters are only displayed as question marks, but internally they are different characters. Otherwise you might want to install an Unicode font, which contains all necessary characters. 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 @@ + --> @@ -10,249 +9,83 @@ - + -AlexWalker
alex@x3ja.co.uk
Conversion to British English +AlexWalker
alex@x3ja.co.uk
Conversion to British English -Glossary +Glossary -A +A - Auxiliary file + Auxiliary file - is a &kbabel; specific issue. It is an option for the user to set up one PO 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 PO file associated with the file currently being translated. + is a &kbabel; specific issue. It is an option for the user to set up one PO 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 PO file associated with the file currently being translated. -C +C - Compendium file + Compendium file - is a collection of all translations for one language. This big PO file is made by unique messages from all applications' PO files. It can be used to fill in all already translated strings into a new yet untranslated or partially translated PO file. &kbabel; uses such a file in the PO Compendium search engine. + is a collection of all translations for one language. This big PO file is made by unique messages from all applications' PO files. It can be used to fill in all already translated strings into a new yet untranslated or partially translated PO file. &kbabel; uses such a file in the PO Compendium search engine. -F +F - Fuzzy + Fuzzy - This is a flag generated, in general, by msgmerge. It shows that a msgstr string might not be a correct translation. The translator must see and make modifications to the string if necessary and then remove the fuzzy flag from the message's comment. + This is a flag generated, in general, by msgmerge. It shows that a msgstr string might not be a correct translation. The translator must see and make modifications to the string if necessary and then remove the fuzzy flag from the message's comment. -I - Internationalisation i18n - is the operation by which an application is made aware and able to support multiple languages. The word internationalisation 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 i18n. - +I + Internationalisation i18n + is the operation by which an application is made aware and able to support multiple languages. The word internationalisation 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 i18n. + -L - Localisation l10n - 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 localisation 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 l10n. - +L + Localisation l10n + 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 localisation 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 l10n. + -M - MO file MO - MO stands for Machine Object. A MO file contains binary data suitable for reading by computers. The contents of a MO file are organised as a database to minimise the lookup time for translated strings. MO files are obtained by compiling PO files using msgfmt. - +M + MO file MO + MO stands for Machine Object. A MO file contains binary data suitable for reading by computers. The contents of a MO file are organised as a database to minimise the lookup time for translated strings. MO files are obtained by compiling PO files using msgfmt. + - Message ID msgid - msgid is the keyword which introduces the original string in a PO file. It is followed by a C-like string that spans one or more lines. - + Message ID msgid + msgid is the keyword which introduces the original string in a PO file. It is followed by a C-like string that spans one or more lines. + - Message String msgstr - msgstr is the keyword which introduces the translated string in PO file. It is followed by C-like string that span on one or multiple lines. - + Message String msgstr + msgstr is the keyword which introduces the translated string in PO file. It is followed by C-like string that span on one or multiple lines. + -P - PO file PO - PO stands for Portable Object. PO files contain sets of strings which associate each translatable string with its translation in a particular language. A single PO file relates to only one language. A PO file is derived from a POT file and is edited either by hand or using &kbabel;. - +P + PO file PO + PO stands for Portable Object. PO files contain sets of strings which associate each translatable string with its translation in a particular language. A single PO file relates to only one language. A PO file is derived from a POT file and is edited either by hand or using &kbabel;. + - POT file POT - POT stands for Portable Object Template. A POT file is built by extracting all the translatable strings from application source files. A POT file does not contain translations into any particular language— it is used by the translators as a template. - + POT file POT + POT stands for Portable Object Template. A POT file is built by extracting all the translatable strings from application source files. A POT file does not contain translations into any particular language— it is used by the translators as a template. + 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 @@ - + ]> -The &kbabel; Handbook +The &kbabel; Handbook -&Stanislav.Visnovsky; &Stanislav.Visnovsky.mail; -&Matthias.Kiefer; -MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English +&Stanislav.Visnovsky; &Stanislav.Visnovsky.mail; +&Matthias.Kiefer; +MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English -2003-09-18 -3.1.91 +2003-09-18 +3.1.91 -&kbabel; is a suite of of an advanced and easy to use PO 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. +&kbabel; is a suite of of an advanced and easy to use PO 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. -KDE -KBabel -catalogmanager -tdesdk -gettext -translation -i18n -l10n +KDE +KBabel +catalogmanager +tdesdk +gettext +translation +i18n +l10n -Introduction - -&kbabel; is an advanced and easy to use PO file (&GNU; gettext message catalogues) editor. It has many features, that make it easy to edit and manage your PO 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 PO 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. - -With the &kde; project growing continuously, the number of PO 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. +Introduction + +&kbabel; is an advanced and easy to use PO file (&GNU; gettext message catalogues) editor. It has many features, that make it easy to edit and manage your PO 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 PO 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. + +With the &kde; project growing continuously, the number of PO 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. @@ -107,68 +65,47 @@ -Credits and Licence - -&kbabel; -Program Copyright © 1999-2000 &Matthias.Kiefer; &Matthias.Kiefer.mail; -Contributors: -&Thomas.Diehl; &Thomas.Diehl.mail; +Credits and Licence + +&kbabel; +Program Copyright © 1999-2000 &Matthias.Kiefer; &Matthias.Kiefer.mail; +Contributors: +&Thomas.Diehl; &Thomas.Diehl.mail; -&Stephan.Kulow; &Stephan.Kulow.mail; +&Stephan.Kulow; &Stephan.Kulow.mail; -Documentation Copyright © 2000 &Claudiu.Costin; &Claudiu.Costin.mail; and &Matthias.Kiefer; &Matthias.Kiefer.mail; +Documentation Copyright © 2000 &Claudiu.Costin; &Claudiu.Costin.mail; and &Matthias.Kiefer; &Matthias.Kiefer.mail; -Update for &kde; 3.0 Copyright © 2002 &Stanislav.Visnovsky; &Stanislav.Visnovsky.mail; +Update for &kde; 3.0 Copyright © 2002 &Stanislav.Visnovsky; &Stanislav.Visnovsky.mail; -Malcolm Huntermalcolm.hunter@gmx.co.uk +Malcolm Huntermalcolm.hunter@gmx.co.uk &underFDL; &underGPL; &glossary; -Installation +Installation -How to obtain &kbabel; +How to obtain &kbabel; &install.intro.documentation; -Requirements +Requirements -In order to successfully use &kbabel;, you need &kde; 3.x. +In order to successfully use &kbabel;, you need &kde; 3.x. -All required libraries as well as &kbabel; itself can be found on &kde-ftp;. +All required libraries as well as &kbabel; itself can be found on &kde-ftp;. -If you want to use the translation database, you need Berkeley Database II. +If you want to use the translation database, you need Berkeley Database II. -Compilation and Installation +Compilation and Installation &install.compile.documentation; 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 @@ + --> @@ -10,82 +9,39 @@ - + -MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English +MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English -Using &kbabeldict; +Using &kbabeldict; -&kbabeldict; is a simple interface for translation modules for &kbabel;. It allows you to search for translations. +&kbabeldict; is a simple interface for translation modules for &kbabel;. It allows you to search for translations. -Screenshot of &kbabeldict; +Screenshot of &kbabeldict; -Screenshot of &kbabeldict; +Screenshot of &kbabeldict; -The screenshot above does not contain settings for selected module. You can show them using Show Settings. Preferences widget for selected module will be shown on the right side of the window. The &kbabeldict; window then looks like this: +The screenshot above does not contain settings for selected module. You can show them using Show Settings. Preferences widget for selected module will be shown on the right side of the window. The &kbabeldict; window then looks like this: -Screenshot of &kbabeldict; +Screenshot of &kbabeldict; -Screenshot of &kbabeldict; with shown settings +Screenshot of &kbabeldict; with shown settings -The usage is very simple. You select a module to in the Search in module combo-box. Then you enter the phrase to lookup and press Start Search. 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 Stop. In case you want to search in translated text, not in original English message, you should use Search in translations. -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. +The usage is very simple. You select a module to in the Search in module combo-box. Then you enter the phrase to lookup and press Start Search. 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 Stop. In case you want to search in translated text, not in original English message, you should use Search in translations. +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. -For description of the standard modules and their settings see . +For description of the standard modules and their settings see . + --> @@ -11,218 +10,116 @@ -AndrewColes +AndrewColes -MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English +MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English -Command Reference +Command Reference -The &kbabel; menu +The &kbabel; menu -The File Menu +The File Menu - &Ctrl;O File Open + &Ctrl;O File Open - Opens a PO file. If the current file is modified you will be prompted to save it first. + Opens a PO file. If the current file is modified you will be prompted to save it first. - File Open Recent + File Open Recent - Opens a recently edited PO file from the recently-used documents menu + Opens a recently edited PO file from the recently-used documents menu - &Ctrl;S File Save + &Ctrl;S File Save - Saves the current PO file. If it is not modified no action is taken. + Saves the current PO file. If it is not modified no action is taken. - File Save As + File Save As - Saves the current PO file under a new name + Saves the current PO file under a new name - File Save Special + File Save Special - Displays the Save Settings dialogue and then saves the current PO file under a new name + Displays the Save Settings dialogue and then saves the current PO file under a new name - File Revert + File Revert - Loads the last saved version of the current PO file + Loads the last saved version of the current PO file - File Mail + File Mail - 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 + 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 - File New View + File New View - Opens a new window with the currently loaded file. Very useful if you have to translate large files and need to refer back to some strings. + Opens a new window with the currently loaded file. Very useful if you have to translate large files and need to refer back to some strings. - File New Window + File New Window - Opens a new empty window + Opens a new empty window - &Ctrl;Q File Quit + &Ctrl;Q File Quit - Quits &kbabel; editor + Quits &kbabel; editor @@ -230,345 +127,162 @@ -The Edit Menu +The Edit Menu - &Ctrl;Z Edit Undo + &Ctrl;Z Edit Undo - Undoes the last edit action in the translation edit box + Undoes the last edit action in the translation edit box - &Ctrl;&Shift;Z Edit Redo + &Ctrl;&Shift;Z Edit Redo - Redoes the last undone edit action in the translation edit box + Redoes the last undone edit action in the translation edit box - &Ctrl;X Edit Cut + &Ctrl;X Edit Cut - Cuts the selected text and moves it to the clipboard + Cuts the selected text and moves it to the clipboard - &Ctrl;C Edit Copy + &Ctrl;C Edit Copy - Copies the selected text to the clipboard + Copies the selected text to the clipboard - &Ctrl;V Edit Paste + &Ctrl;V Edit Paste - Pastes the contents of the clipboard at the current cursor position in the translation edit box. + Pastes the contents of the clipboard at the current cursor position in the translation edit box. - Edit Select All + Edit Select All - Selects all text in the translation edit box + Selects all text in the translation edit box - &Ctrl;F Edit Find... + &Ctrl;F Edit Find... - Opens a Find dialogue for searching for strings in the current PO file + Opens a Find dialogue for searching for strings in the current PO file - F3 Edit Find Next + F3 Edit Find Next - Finds the next occurrence of a string from the previous search action + Finds the next occurrence of a string from the previous search action - &Ctrl;R Edit Replace... + &Ctrl;R Edit Replace... - Opens the Replace dialogue to search for and replace strings in the current PO file + Opens the Replace dialogue to search for and replace strings in the current PO file - &Ctrl;Delete Edit Clear + &Ctrl;Delete Edit Clear - Clears the translation for the current msgid + Clears the translation for the current msgid - &Ctrl;Space Edit Copy msgid to msgstr + &Ctrl;Space Edit Copy msgid to msgstr - 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). + 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). - &Ctrl;&Alt;Space Edit Copy search result to msgstr + &Ctrl;&Alt;Space Edit Copy search result to msgstr - 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. + 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. - &Ctrl;U Edit Toggle Fuzzy Status + &Ctrl;U Edit Toggle Fuzzy Status - Toggles the fuzzy status for the current entry. It can be useful to turn fuzzy on, ⪚ to mark the translation for another review. + Toggles the fuzzy status for the current entry. It can be useful to turn fuzzy on, ⪚ to mark the translation for another review. - &Ctrl;&Alt;N Edit Insert Next Tag + &Ctrl;&Alt;N Edit Insert Next Tag - Inserts the next tag found in the msgid into the translation, if the original English string contains markup tags + Inserts the next tag found in the msgid into the translation, if the original English string contains markup tags - &Ctrl;&Alt;N Edit Insert Tag + &Ctrl;&Alt;N Edit Insert Tag - 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. + 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. - Edit Edit Header... + Edit Edit Header... - Edits the PO file header. Actually there are many header lines, which keep the last translated date, translator name and email, language and translated text encoding &etc;. + Edits the PO file header. Actually there are many header lines, which keep the last translated date, translator name and email, language and translated text encoding &etc;. @@ -576,318 +290,152 @@ -The Go Menu +The Go Menu - Page Up Go Previous + Page Up Go Previous - Skips to the previous entry in the PO file. + Skips to the previous entry in the PO file. - Page Down Go Next + Page Down Go Next - Skips to the next entry in the PO file. + Skips to the next entry in the PO file. - Go Go to... + Go Go to... - Opens a dialogue to jump to a specific entry number within the PO file. + Opens a dialogue to jump to a specific entry number within the PO file. - Go First Entry + Go First Entry - Jumps to the first entry in the PO file. + Jumps to the first entry in the PO file. - Go Last Entry + Go Last Entry - Jumps to the last entry in the PO file. + Jumps to the last entry in the PO file. - &Ctrl;&Shift;Page Up Go Previous fuzzy or untranslated + &Ctrl;&Shift;Page Up Go Previous fuzzy or untranslated - Jumps to the entry previous to the current one that is untranslated or marked as fuzzy. + Jumps to the entry previous to the current one that is untranslated or marked as fuzzy. - &Ctrl;&Shift;Page Down Go Next fuzzy or untranslated + &Ctrl;&Shift;Page Down Go Next fuzzy or untranslated - Jumps to the next entry after the current one which is untranslated or marked as fuzzy. + Jumps to the next entry after the current one which is untranslated or marked as fuzzy. - &Ctrl;PgUp Go Previous fuzzy + &Ctrl;PgUp Go Previous fuzzy - Jumps to the entry previous to the current one that is marked as fuzzy. + Jumps to the entry previous to the current one that is marked as fuzzy. - &Ctrl;Page Down Go Next fuzzy + &Ctrl;Page Down Go Next fuzzy - Jumps to the next entry after the current one that is marked as fuzzy. + Jumps to the next entry after the current one that is marked as fuzzy. - &Alt;Page Up Go Previous untranslated + &Alt;Page Up Go Previous untranslated - Jumps to the entry previous to the current one that is untranslated. + Jumps to the entry previous to the current one that is untranslated. - &Alt;Page Down Go Next untranslated + &Alt;Page Down Go Next untranslated - Jumps to the next entry after the current one that is untranslated. + Jumps to the next entry after the current one that is untranslated. - &Shift;Page Up Go Previous error + &Shift;Page Up Go Previous error - 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). + 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). - &Shift;Page Down Go Next error + &Shift;Page Down Go Next error - Jumps to the next entry with an error. + Jumps to the next entry with an error. - &Alt;Left Arrow Go Back + &Alt;Left Arrow Go Back - Jump to last visited entry in PO file. + Jump to last visited entry in PO file. - &Alt;Right Arrow Go Forward + &Alt;Right Arrow Go Forward - Jump to previous visited entry in PO file. + Jump to previous visited entry in PO file. @@ -895,138 +443,70 @@ -The Dictionaries Menu -Note that this menu is dynamic: it depends on the installed dictionaries plugins. By default are three of them. +The Dictionaries Menu +Note that this menu is dynamic: it depends on the installed dictionaries plugins. By default are three of them. - Dictionaries Search Text KDE Database Search Engine + Dictionaries Search Text KDE Database Search Engine - Start searching translation for current original English message using &kde; Database Search Engine. + Start searching translation for current original English message using &kde; Database Search Engine. - Dictionaries Search Text PO Auxiliary + Dictionaries Search Text PO Auxiliary - Start searching translation for current original English message in PO file defined by user. + Start searching translation for current original English message in PO file defined by user. - Dictionaries Search Text PO Compendium + Dictionaries Search Text PO Compendium - Start searching translation for current original English message in compendium file (made by merging all translated messages for one language). + Start searching translation for current original English message in compendium file (made by merging all translated messages for one language). - Dictionaries Search Selected Text KDE Database Search Engine + Dictionaries Search Selected Text KDE Database Search Engine - Start searching selected text using &kde; Database Search Engine. + Start searching selected text using &kde; Database Search Engine. - Dictionaries Search Selected Text PO Auxiliary + Dictionaries Search Selected Text PO Auxiliary - Start searching selected text using file defined by user. + Start searching selected text using file defined by user. - Dictionaries Search Selected Text PO Compendium + Dictionaries Search Selected Text PO Compendium - Start searching selected text using compendium file with all language translated messages. + Start searching selected text using compendium file with all language translated messages. - Dictionaries Edit Dictionary + Dictionaries Edit Dictionary - 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. (Not implemented yet) + 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. (Not implemented yet) @@ -1035,725 +515,352 @@ -The Tools Menu +The Tools Menu - Tools Spelling Spell check... + Tools Spelling Spell check... - Display the spell-check configuration dialogue. After you have chosen the desired options, hit OK and the normal spell-checking dialogue will appear. + Display the spell-check configuration dialogue. After you have chosen the desired options, hit OK and the normal spell-checking dialogue will appear. - Tools Spelling Check All... + Tools Spelling Check All... - Start spell-checking all words for an opened PO file. + Start spell-checking all words for an opened PO file. - Tools Spelling Check From Cursor Position... + Tools Spelling Check From Cursor Position... - Start spell-checking from current cursor position. + Start spell-checking from current cursor position. - Tools Spelling Check Current... + Tools Spelling Check Current... - Spell-check only current entry from PO file. + Spell-check only current entry from PO file. - Tools Spelling Check Marked Text... + Tools Spelling Check Marked Text... - Spell-check only selected text in MsgStr editbox. + Spell-check only selected text in MsgStr editbox. - &Ctrl;T Tools Validation Check Syntax + &Ctrl;T Tools Validation Check Syntax - Check syntax for current PO file. Errors may appear from CVS merging or users' mistakes when the translating process is performed by hand. + Check syntax for current PO file. Errors may appear from CVS merging or users' mistakes when the translating process is performed by hand. - &Ctrl;D Tools Validation Check Arguments + &Ctrl;D Tools Validation Check Arguments - 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. + 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. - &Ctrl;H Tools Validation Check Accelerators + &Ctrl;H Tools Validation Check Accelerators - When this option is selected, &kbabel; checks if the number of accelerator characters is identical in both the original and the translated string. Note that accelerator marker is & in &kde; (but not in every programming toolkit). See the Miscellaneous section below to find out how to change a keyboard accelerator. + When this option is selected, &kbabel; checks if the number of accelerator characters is identical in both the original and the translated string. Note that accelerator marker is & in &kde; (but not in every programming toolkit). See the Miscellaneous section below to find out how to change a keyboard accelerator. - &Ctrl;K Tools Validation Look for Translated Context Info + &Ctrl;K Tools Validation Look for Translated Context Info - 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 Save, are translated into many languages. Context information is marked with _:. 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. + 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 Save, are translated into many languages. Context information is marked with _:. 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. - Tools Validation Check Plural Forms (KDE only) + Tools Validation Check Plural Forms (KDE only) - Check if the PO file contains the correct number of translations for each &kde;-specific plural form message. + Check if the PO file contains the correct number of translations for each &kde;-specific plural form message. - &Ctrl;J Tools Validation Check Equations + &Ctrl;J Tools Validation Check Equations - 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. + 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. - F5 Tools Diff Show Diff + F5 Tools Diff Show Diff - Show difference found to the original translated message. + Show difference found to the original translated message. - F6 Tools Diff Show Original Text + F6 Tools Diff Show Original Text - Hide difference markings and show msgid only. + Hide difference markings and show msgid only. - Tools Diff Open File for Diff + Tools Diff Open File for Diff - Open file to be used for difference lookup. + Open file to be used for difference lookup. - Tools Diff Diffmode + Tools Diff Diffmode - Toggle difference mode. + Toggle difference mode. - Tools Rough Translation... + Tools Rough Translation... - Invoke rough-translation dialogue for automated translation. + Invoke rough-translation dialogue for automated translation. - Tools Catalogue Manager... + Tools Catalogue Manager... - Open &catalogmanager;. Read &catalogmanager; section for more details. + Open &catalogmanager;. Read &catalogmanager; section for more details. -The Settings Menu +The Settings Menu - Settings Show Toolbar + Settings Show Toolbar - When checked, the standard toolbar is displayed. + When checked, the standard toolbar is displayed. - Settings Show Statusbar + Settings Show Statusbar - When checked, the bottom statusbar is displayed. + When checked, the bottom statusbar is displayed. - Settings Show Navigation Bar + Settings Show Navigation Bar - When checked, the navigation bar is displayed. + When checked, the navigation bar is displayed. - Settings Show Comments + Settings Show Comments - When checked, the upper-right part of main window, which contains current entry's comments, will be displayed. + When checked, the upper-right part of main window, which contains current entry's comments, will be displayed. - Settings Show Tools + Settings Show Tools - When checked, the bottom-right part of main window, which contain search results through the dictionary, will be displayed. + When checked, the bottom-right part of main window, which contain search results through the dictionary, will be displayed. - Settings Configure Key Bindings... + Settings Configure Key Bindings... - Opens a configure dialogue for binding keys to actions. This will let you to customise the default key bindings to suite your needs. + Opens a configure dialogue for binding keys to actions. This will let you to customise the default key bindings to suite your needs. - Settings Configure Toolbars... + Settings Configure Toolbars... - Standard toolbar-configuration dialogue will open. You can choose which actions will go in which toolbars and what toolbar to customise. + Standard toolbar-configuration dialogue will open. You can choose which actions will go in which toolbars and what toolbar to customise. - Settings Configure Kbabel... + Settings Configure Kbabel... - All &kbabel;-specific settings go here. Please read the Preferences section for specific topics. + All &kbabel;-specific settings go here. Please read the Preferences section for specific topics. - Settings Configure Dictionary KDE Database Search Engine + Settings Configure Dictionary KDE Database Search Engine - Open dialogue for &kde; Database Search Engine configuration. + Open dialogue for &kde; Database Search Engine configuration. - Settings Configure Dictionary PO Auxiliary + Settings Configure Dictionary PO Auxiliary - Open dialogue for PO auxiliary file configuration. + Open dialogue for PO auxiliary file configuration. - Settings Configure Dictionary PO Compendium + Settings Configure Dictionary PO Compendium - Open dialogue for PO compendium file configuration. + Open dialogue for PO compendium file configuration. -The Help Menu +The Help Menu - F1 Help Contents + F1 Help Contents - Open the &kbabel; handbook. It is what you are reading now. + Open the &kbabel; handbook. It is what you are reading now. - &Shift;F1 Help What's This? + &Shift;F1 Help What's This? - 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. + 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. - Help Gettext Info + Help Gettext Info - Open the gettext manual page in the &kde; Help Centre. This package of tools helps the in process of handling POT and PO files. + Open the gettext manual page in the &kde; Help Centre. This package of tools helps the in process of handling POT and PO files. - Help Report Bug... + Help Report Bug... - This will open a standard error-reporting dialogue 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. + This will open a standard error-reporting dialogue 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. - Help About KBabel... + Help About KBabel... - Open a message box which inform you about &kbabel;'s version, developer name, and e-mail address. + Open a message box which inform you about &kbabel;'s version, developer name, and e-mail address. - Help About KDE... + Help About KDE... - Open a message box which informs you about the &kde; project, contact information and how you can report bugs and wishes. + Open a message box which informs you about the &kde; project, contact information and how you can report bugs and wishes. - Help About Dictionary KDE Database Search Engine + Help About Dictionary KDE Database Search Engine - Display a message box with information about the people who made the &kde; Database Search Engine. + Display a message box with information about the people who made the &kde; Database Search Engine. - Help About Dictionary PO Auxiliary + Help About Dictionary PO Auxiliary - Display a message box with information about the people who made searching in auxiliary file possible. + Display a message box with information about the people who made searching in auxiliary file possible. - Help About Dictionary PO Compendium + Help About Dictionary PO Compendium - Display a message box with information about people who made searching in compendium file possible. + Display a message box with information about people who made searching in compendium file possible. @@ -1762,12 +869,10 @@ -The &kbabel; toolbars +The &kbabel; toolbars -Standard Toolbar +Standard Toolbar @@ -1775,13 +880,9 @@ - Open + Open - Load PO file in &kbabel; for editing. + Load PO file in &kbabel; for editing. @@ -1790,13 +891,9 @@ - Save + Save - Save current PO file if it is modified. + Save current PO file if it is modified. @@ -1805,11 +902,9 @@ - Undo + Undo - Undo last operation. + Undo last operation. @@ -1818,11 +913,9 @@ - Redo + Redo - Redo last operation. + Redo last operation. @@ -1831,11 +924,9 @@ - Cut + Cut - Cut selected text and move it to the clipboard. + Cut selected text and move it to the clipboard. @@ -1844,11 +935,9 @@ - Copy + Copy - Copy selected text to the clipboard. + Copy selected text to the clipboard. @@ -1857,11 +946,9 @@ - Paste + Paste - Paste text from clipboard at the current cursor position. + Paste text from clipboard at the current cursor position. @@ -1870,11 +957,9 @@ - Find + Find - Find specified string in current PO-file. + Find specified string in current PO-file. @@ -1883,11 +968,9 @@ - Previous + Previous - Skip to previous entry in PO-file. + Skip to previous entry in PO-file. @@ -1896,13 +979,9 @@ - Next + Next - Skip to next entry in PO file. + Skip to next entry in PO file. @@ -1911,15 +990,9 @@ - Copy msgid to msgstr + Copy msgid to msgstr - Copy original string to translated string edit box. + Copy original string to translated string edit box. @@ -1928,15 +1001,9 @@ - Search Translations + Search Translations - Drop-down toolbar for searching selected text using: &kde; Database Search Engine, PO auxiliary file, PO compendium file and other dictionary plugins if available. + Drop-down toolbar for searching selected text using: &kde; Database Search Engine, PO auxiliary file, PO compendium file and other dictionary plugins if available. @@ -1945,11 +1012,9 @@ - Stop + Stop - Stop current search-in-progress. + Stop current search-in-progress. @@ -1958,19 +1023,16 @@ - Catalogue Manager + Catalogue Manager - Open Catalogue Manager window. + Open Catalogue Manager window. -Navigation Toolbar +Navigation Toolbar @@ -1978,13 +1040,9 @@ - Previous + Previous - Skip to previous entry in PO file. + Skip to previous entry in PO file. @@ -1993,13 +1051,9 @@ - Next + Next - Skip to next entry in PO file. + Skip to next entry in PO file. @@ -2008,13 +1062,9 @@ - First Entry + First Entry - Jump to first entry in PO file. + Jump to first entry in PO file. @@ -2023,13 +1073,9 @@ - Last Entry + Last Entry - Jump to last entry in PO file. + Jump to last entry in PO file. @@ -2038,13 +1084,9 @@ - Previous fuzzy or untranslated + Previous fuzzy or untranslated - Jump to previous fuzzy or untranslated entry in PO file. + Jump to previous fuzzy or untranslated entry in PO file. @@ -2053,13 +1095,9 @@ - Next fuzzy or untranslated + Next fuzzy or untranslated - Jump to next fuzzy or untranslated entry in PO file. + Jump to next fuzzy or untranslated entry in PO file. @@ -2068,13 +1106,9 @@ - Previous fuzzy + Previous fuzzy - Jump to previous fuzzy entry in PO file. + Jump to previous fuzzy entry in PO file. @@ -2083,13 +1117,9 @@ - Next fuzzy + Next fuzzy - Jump to next fuzzy entry in PO file. + Jump to next fuzzy entry in PO file. @@ -2098,13 +1128,9 @@ - Previous untranslated + Previous untranslated - Jump to previous untranslated entry in PO file. + Jump to previous untranslated entry in PO file. @@ -2113,13 +1139,9 @@ - Next untranslated + Next untranslated - Jump to next untranslated entry in PO file. + Jump to next untranslated entry in PO file. @@ -2128,13 +1150,9 @@ - Previous error + Previous error - Jump to previous error in PO file. + Jump to previous error in PO file. @@ -2143,13 +1161,9 @@ - Next error + Next error - Jump to next error in PO file. + Jump to next error in PO file. @@ -2158,13 +1172,9 @@ - Back + Back - Jump to last visited entry in PO file. + Jump to last visited entry in PO file. @@ -2173,80 +1183,57 @@ - Forward + Forward - Jump to previous visited entry in PO file. + Jump to previous visited entry in PO file. -Status Bar +Status Bar - Current + Current - Current message in edited PO file. + Current message in edited PO file. - Total + Total - Total number of messages in PO file. + Total number of messages in PO file. - Fuzzy + Fuzzy - Number of messages marked as fuzzy. They should be revised and translated if needed. + Number of messages marked as fuzzy. They should be revised and translated if needed. - Untranslated + Untranslated - Number of yet untranslated messages. + Number of yet untranslated messages. - Editor status + Editor status - INS - insert, and OVR - overwrite. Same meaning like in every ordinary text editor. + INS - insert, and OVR - overwrite. Same meaning like in every ordinary text editor. - PO-file status + PO-file status - RO - read-only file, RW - read-write access on file. When a file is read-only you cannot modify entries in editor. + RO - read-only file, RW - read-write access on file. When a file is read-only you cannot modify entries in editor. - Progress bar + Progress bar - 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. + 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. @@ -2255,32 +1242,18 @@ -The &catalogmanager; menu +The &catalogmanager; menu -The File Menu +The File Menu - &Ctrl;Q File Quit + &Ctrl;Q File Quit - Quits &catalogmanager; + Quits &catalogmanager; @@ -2288,142 +1261,75 @@ -The Edit Menu +The Edit Menu - &Ctrl;F Edit Find in Files... + &Ctrl;F Edit Find in Files... - Open Find dialogue for searching for strings in a set of PO files. + Open Find dialogue for searching for strings in a set of PO files. - &Ctrl;R Edit Replace in Files... + &Ctrl;R Edit Replace in Files... - Open Replace dialogue for searching for and replacing strings in a set of PO files. + Open Replace dialogue for searching for and replacing strings in a set of PO files. - Escape Edit Stop Searching + Escape Edit Stop Searching - Stop currently running find/replace operation. + Stop currently running find/replace operation. - &Ctrl;M Edit Toggle Marking + &Ctrl;M Edit Toggle Marking - Toggle mark for the selected file. + Toggle mark for the selected file. - Edit Remove Marking + Edit Remove Marking - Removes mark for the selected file or folder. + Removes mark for the selected file or folder. - Edit Toggle All Markings + Edit Toggle All Markings - Toggles marks for the selected file or folder (recursively). + Toggles marks for the selected file or folder (recursively). - Edit Remove All Markings + Edit Remove All Markings - Remove marks for the selected file or folder (recursively). + Remove marks for the selected file or folder (recursively). @@ -2431,50 +1337,25 @@ -The Tools Menu +The Tools Menu - &Ctrl;S Tools Statistics + &Ctrl;S Tools Statistics - Show statistics about number of translated/untranslated/fuzzy messages for the selected file or subtree. + Show statistics about number of translated/untranslated/fuzzy messages for the selected file or subtree. - &Ctrl;Y Tools Check Syntax + &Ctrl;Y Tools Check Syntax - Check syntax for the selected file or subtree using msgfmt. + Check syntax for the selected file or subtree using msgfmt. @@ -2482,101 +1363,64 @@ -The Settings Menu +The Settings Menu - Settings Show Toolbar + Settings Show Toolbar - When checked, standard toolbar is displayed. + When checked, standard toolbar is displayed. - Settings Show Statusbar + Settings Show Statusbar - When checked, bottom statusbar is displayed. + When checked, bottom statusbar is displayed. - Settings Configure Key Bindings... + Settings Configure Key Bindings... - Opens a configure dialogue for binding keys to actions. This will let you to customise the default key bindings to suite your needs. + Opens a configure dialogue for binding keys to actions. This will let you to customise the default key bindings to suite your needs. - Settings Configure Toolbars... + Settings Configure Toolbars... - Standard toolbar-configuration dialogue will open. You can choose which actions will go in which toolbars and what toolbar to customise. + Standard toolbar-configuration dialogue will open. You can choose which actions will go in which toolbars and what toolbar to customise. - Settings Configure KBabel - Catalogue Manager... + Settings Configure KBabel - Catalogue Manager... - All &catalogmanager; specific settings go here. Please read Preferences section for specific topics. + All &catalogmanager; specific settings go here. Please read Preferences section for specific topics. -The Help Menu +The Help Menu &help.menu.documentation; - + + --> @@ -11,95 +10,35 @@ - + -AlexWalker
alex@x3ja.co.uk
Conversion to British English +AlexWalker
alex@x3ja.co.uk
Conversion to British English -Preferences +Preferences -&kbabel; preferences - -To show the Preferences dialogue choose Settings Configure KBabel... 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. - -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 OK 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. +&kbabel; preferences + +To show the Preferences dialogue choose Settings Configure KBabel... 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. + +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 OK 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. -Identity - -This section allows you to set standard fields for every translated PO 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 last modified time for PO files. You can specify it as character sequence like EEST or offset from GMT 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 Save section of the Preferences dialogue. - -Character sequences for timezones are not standardised. So you should not use the string set here in time specification for saving in Save tab. You should use %z instead. +Identity + +This section allows you to set standard fields for every translated PO 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 last modified time for PO files. You can specify it as character sequence like EEST or offset from GMT 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 Save section of the Preferences dialogue. + +Character sequences for timezones are not standardised. So you should not use the string set here in time specification for saving in Save tab. You should use %z instead. -Number of singular/plural forms +Number of singular/plural forms -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). - -This feature is currently implemented only for plural forms format used in &kde;. It does not work with gettext plural forms. +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). + +This feature is currently implemented only for plural forms format used in &kde;. It does not work with gettext plural forms. @@ -107,148 +46,61 @@ -Editor -The editor preferences category is divided in 3 subwindows: General, Appearance, Spell Check and Fonts. All these settings customize how the editor behaves and looks. +Editor +The editor preferences category is divided in 3 subwindows: General, Appearance, Spell Check and Fonts. All these settings customize how the editor behaves and looks. -General - -This section contains a set of checkboxes. - -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 EditUnset Fuzzy Status or use the &Ctrl;U shortcut. Note that this means the string , fuzzy is removed from the entry's comment. - -Next option allows you to enable clever editing, where editor automatically inserts special characters escaped correctly, ⪚ \t after pressing Tab and it allows special handling of Enter. - -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. +General + +This section contains a set of checkboxes. + +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 EditUnset Fuzzy Status or use the &Ctrl;U shortcut. Note that this means the string , fuzzy is removed from the entry's comment. + +Next option allows you to enable clever editing, where editor automatically inserts special characters escaped correctly, ⪚ \t after pressing Tab and it allows special handling of Enter. + +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. - Check Arguments + Check Arguments - 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. + 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. - Check Accelerator + Check Accelerator -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 Miscellaneous section below to find how to change a keyboard accelerator. +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 Miscellaneous section below to find how to change a keyboard accelerator. - Check Equation + Check Equation - This is a feature for the &kde; project development. .desktop files are simply text files which store various parameters in value=key format. Some of these keys 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 msgmerge algorithm. Note that there are situations where this function generates false errors on some PO-files. + This is a feature for the &kde; project development. .desktop files are simply text files which store various parameters in value=key format. Some of these keys 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 msgmerge algorithm. Note that there are situations where this function generates false errors on some PO-files. - Look for Translated Context Info + Look for Translated Context Info -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 Save, are translated into many languages. Context information is marked with _:. 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. +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 Save, are translated into many languages. Context information is marked with _:. 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. - Check Plural Forms + Check Plural Forms - 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 msgstr and compares it with the number specified in Identity tab. Incorrect number of plural forms can result in crash of an application. + 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 msgstr and compares it with the number specified in Identity tab. Incorrect number of plural forms can result in crash of an application. - Beep on error + Beep on error - Your system bell will beep when you switch on entries with errors like those described above. + Your system bell will beep when you switch on entries with errors like those described above. - Change text colour on error + Change text colour on error - 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 Appearance tab to find out how to change the text colour on errors. + 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 Appearance tab to find out how to change the text colour on errors. @@ -256,724 +108,302 @@ -Appearance +Appearance -These options let you configure the appearance for the message editor. In upper part there are 4 checkboxes: +These options let you configure the appearance for the message editor. In upper part there are 4 checkboxes: - Highlight syntax - 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. + Highlight syntax + 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. - Highlight background - 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 PO entry, and you will still be able to observe starting and ending spaces in a text line. + Highlight background + 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 PO entry, and you will still be able to observe starting and ending spaces in a text line. - Mark whitespaces with points - 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. + Mark whitespaces with points + 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. - Show surrounding quotes - 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. - If you are experienced editing PO files with ordinary text editors you may feel safer if you can track starting and ending double quotes in PO entry lines. + Show surrounding quotes + 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. + If you are experienced editing PO files with ordinary text editors you may feel safer if you can track starting and ending double quotes in PO entry lines. -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. +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. - Background colour - 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;. + Background colour + 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;. - Colour for quoted characters - Here you can adjust the colour for escaped characters like (\") double quotes or (\n) newline. + Colour for quoted characters + Here you can adjust the colour for escaped characters like (\") double quotes or (\n) newline. - Colour for syntax errors - This is the colour for the entire text entry if errors are detected when you try to save PO file. Errors are triggered by not terminating identically both msgid and msgstr, or escaping characters incorrectly. + Colour for syntax errors + This is the colour for the entire text entry if errors are detected when you try to save PO file. Errors are triggered by not terminating identically both msgid and msgstr, or escaping characters incorrectly. - Colour for c-format characters - This sets the colour for a characters sequence like in C language printf or scanf functions. In general these start with (%) percent char and are continued by one char. + Colour for c-format characters + This sets the colour for a characters sequence like in C language printf or scanf functions. In general these start with (%) percent char and are continued by one char. - Colour for keyboard accelerators - Keyboard accelerators start with (&) ampersand character in &kde; but if you are translating for other projects there might be an different character marking the accelerator key. See Miscellaneous section below to find how to change keyboard accelerator. + Colour for keyboard accelerators + Keyboard accelerators start with (&) ampersand character in &kde; but if you are translating for other projects there might be an different character marking the accelerator key. See Miscellaneous section below to find how to change keyboard accelerator. -The status for the current edited entry is marked by three LEDs. For your convenience you can choose where to put these LEDs—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 LED status changes easily without moving your eye you can select the preferred color using the colour button chooser. +The status for the current edited entry is marked by three LEDs. For your convenience you can choose where to put these LEDs—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 LED status changes easily without moving your eye you can select the preferred color using the colour button chooser. -Fonts +Fonts -This is a standard &kde; font chooser dialogue with a little addition. You can select to view only fixed fonts by checking the Show only fixed fonts 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. +This is a standard &kde; font chooser dialogue with a little addition. You can select to view only fixed fonts by checking the Show only fixed fonts 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. -Save -This section allows you to edit the options for PO file saving. The first group of checkboxes controls general behaviour for actions performed in PO file saving. +Save +This section allows you to edit the options for PO file saving. The first group of checkboxes controls general behaviour for actions performed in PO file saving. - Update header when saving - 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 Fields to update 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 Edit Edit Header in the editor window. + Update header when saving + 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 Fields to update 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 Edit Edit Header in the editor window. - Check syntax of file when saving - Check this to automatically check syntax of file with msgfmt --statistics 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. + Check syntax of file when saving + Check this to automatically check syntax of file with msgfmt --statistics 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. -If you don't want to touch some fields in a PO file header or want to force updating of specific fields, there are five checkboxes which control this: revision date, PO 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 EditEdit Header in the editor window. Deactivate Update header when saving above if you don't want to have the header updated. - -For date and time of the header field PO-Revision-Date you can choose one from bellow formats: +If you don't want to touch some fields in a PO file header or want to force updating of specific fields, there are five checkboxes which control this: revision date, PO 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 EditEdit Header in the editor window. Deactivate Update header when saving above if you don't want to have the header updated. + +For date and time of the header field PO-Revision-Date you can choose one from bellow formats: - Default is the format normally used in PO files. - Local is the format specific to your country. - Custom lets you define your own format, where you can use the following C-like format strings: - Year + Default is the format normally used in PO files. + Local is the format specific to your country. + Custom lets you define your own format, where you can use the following C-like format strings:
+ Year - FormatMeaningRange + FormatMeaningRange - %yyear00 to 99 + %yyear00 to 99 - %Yyear0001 to 9999 + %Yyear0001 to 9999
- Month + Month - FormatMeaningRange + FormatMeaningRange - %mmonth of year01 to 12 + %mmonth of year01 to 12 - %fmonth of year1 to 12 + %fmonth of year1 to 12 - %b,%hmonth abbreviationJan to Dec + %b,%hmonth abbreviationJan to Dec
- Day + Day - FormatMeaningRange + FormatMeaningRange - %jday of the year001 to 366 + %jday of the year001 to 366 - %dday of month01 to 31 + %dday of month01 to 31 - %eday of month1 to 31 + %eday of month1 to 31 - %aweekday abbreviationSun to Sat + %aweekday abbreviationSun to Sat
- Hour + Hour - FormatMeaningRange + FormatMeaningRange - %Hhour00 to 23 + %Hhour00 to 23 - %khour0 to 23 + %khour0 to 23 - %ihour1 to 12 + %ihour1 to 12 - %Ihour01 to 12 + %Ihour01 to 12 - %pAM or PM + %pAM or PM
- Minute, Second, Timezone + Minute, Second, Timezone - FormatMeaningRange + FormatMeaningRange - %Mminute00 to 59 + %Mminute00 to 59 - %Ssecond00 to 59 + %Ssecond00 to 59 - %Ztimezone(given in identity settings) + %Ztimezone(given in identity settings) - %ztimezone(numeric offset as specified by system settings) + %ztimezone(numeric offset as specified by system settings)
- + -The lower group covers encoding options for PO files when saving. If you work on the &kde; project you should be aware that at least desktop.po file must 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 Keep the encoding of the file. +The lower group covers encoding options for PO files when saving. If you work on the &kde; project you should be aware that at least desktop.po file must 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 Keep the encoding of the file. -Spell Check +Spell Check -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: +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: - Create root/affix combinations not in dictionary - For new words added to the personal dictionary, the spell checker will create root/affix combinations to match more than one word (variations). + Create root/affix combinations not in dictionary + For new words added to the personal dictionary, the spell checker will create root/affix combinations to match more than one word (variations). - Consider run-together words as spelling errors - 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. + Consider run-together words as spelling errors + 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. - Dictionary - 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. + Dictionary + 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. - Encoding - 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 tdespell documentation for more details. + Encoding + 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 tdespell documentation for more details. - Client - Backend program to use for spell checking. Currently either ispell (International Ispell) or aspell. + Client + Backend program to use for spell checking. Currently either ispell (International Ispell) or aspell. - Remember ignored words - Keep track of user-ignored words when spell-checking PO files. It is very convenient to ignore the abbreviations or strange letter combinations you meet in &GUI; interfaces. + Remember ignored words + Keep track of user-ignored words when spell-checking PO files. It is very convenient to ignore the abbreviations or strange letter combinations you meet in &GUI; interfaces. - File to store ignored words - 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 $(HOME)/.trinity/share/apps/kbabel/spellignores, where $(HOME) is your home folder. + File to store ignored words + 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 $(HOME)/.trinity/share/apps/kbabel/spellignores, where $(HOME) is your home folder. -Search -The search section allows you to customise various settings for searching in previously translated strings. +Search +The search section allows you to customise various settings for searching in previously translated strings. -General - -General settings are common for all search types. If you check the Automatically start search 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 Settings Configure Dictionary ... you can configure every search plugin. - -The dictionary plugins installed by default are: +General + +General settings are common for all search types. If you check the Automatically start search 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 Settings Configure Dictionary ... you can configure every search plugin. + +The dictionary plugins installed by default are: -&kde; Database Search Engine +&kde; Database Search Engine -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. +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. -PO Compendium -The compendium is a normal PO 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 $lang.messages file in the &kde; Project, that can be found at i18n.kde.org). +PO Compendium +The compendium is a normal PO 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 $lang.messages file in the &kde; Project, that can be found at i18n.kde.org). -PO Auxiliary -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. +PO Auxiliary +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. -You can also start searching manually by choosing an entry in the popup menu that appears, either by clicking DictionariesSearch Text PO Compendium or by keeping the search button on the toolbar pressed down for a while. +You can also start searching manually by choosing an entry in the popup menu that appears, either by clicking DictionariesSearch Text PO Compendium or by keeping the search button on the toolbar pressed down for a while. -Diff - -The Diff section holds settings how to display differences in msgids. - -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. Highlighted means that the background of the corresponding characters will be shown in the selected colour, while Underlined(for added characters) or Stroked Out (for removed characters) will denote the changed parts by coloured lines. -Diff mode needs to find the original msgid to compare with. For this purpose, &kbabel; can use the translation database if you turn in on by enabling Use messages from Translation Database. A second possibility is to use a tree of original PO files and specifying the root of the tree in Base folder for diff files. +Diff + +The Diff section holds settings how to display differences in msgids. + +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. Highlighted means that the background of the corresponding characters will be shown in the selected colour, while Underlined(for added characters) or Stroked Out (for removed characters) will denote the changed parts by coloured lines. +Diff mode needs to find the original msgid to compare with. For this purpose, &kbabel; can use the translation database if you turn in on by enabling Use messages from Translation Database. A second possibility is to use a tree of original PO files and specifying the root of the tree in Base folder for diff files. -Miscellaneous -Miscellaneous section holds settings which don't fit anywhere else. Currently there are two: +Miscellaneous +Miscellaneous section holds settings which don't fit anywhere else. Currently there are two: - Marker for keyboard accelerator - 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 _ is the marker for the keyboard accelerator. + Marker for keyboard accelerator + 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 _ is the marker for the keyboard accelerator. - Regular expression for context information - 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 PO 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". + Regular expression for context information + 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 PO 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". @@ -982,233 +412,61 @@ -&cataloguemanager; preferences +&cataloguemanager; preferences -This dialogue allows you to edit the options for the Catalogue Manager. +This dialogue allows you to edit the options for the Catalogue Manager. -General -Here are two edit lines with Browse... buttons. Type in the folders which contains all your PO- and respectively POT-files. The files and the folders in these folders will then be merged into one tree in Catalogue Manager window. - -Below you can turn on and off if: +General +Here are two edit lines with Browse... buttons. Type in the folders which contains all your PO- and respectively POT-files. The files and the folders in these folders will then be merged into one tree in Catalogue Manager window. + +Below you can turn on and off if: - Open files in new window - If this is activated all files that are opened from the Catalogue Manager are opened in a new window. + Open files in new window + If this is activated all files that are opened from the Catalogue Manager are opened in a new window. - Kill processes on exit - 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. It's not guaranteed that the processes are killed. - + Kill processes on exit + 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. It's not guaranteed that the processes are killed. + - Create index for file contents - 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. There is a large speed trade-off. If you enable Create index for file contents, the updating of file information will be much slower. On the other hand, it speeds up find/replace operations considerably. - + Create index for file contents + 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. There is a large speed trade-off. If you enable Create index for file contents, the updating of file information will be much slower. On the other hand, it speeds up find/replace operations considerably. + -Folder Commands -Here you can insert commands you want to execute in folders from the Catalogue Manager. The commands are then shown in the submenu Commands in the Catalogue Manager's context menu. Insert in the Name field the name of the command. The name can be chosen freely and is only used to be displayed in the menu. In the Command field insert the command you want to have executed when selecting the corresponding menu item. Then press the Add button to add the command to your available commands. To edit a command, select it, press the Edit button and press Add after you have finished. To remove a command, select it from the list and press the Remove button. If you want a different order in the contextual submenu, you can use the up and down buttons. 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 (PO file) folder you have selected in the Catalogue Manager. The following strings will be replaced in a command: +Folder Commands +Here you can insert commands you want to execute in folders from the Catalogue Manager. The commands are then shown in the submenu Commands in the Catalogue Manager's context menu. Insert in the Name field the name of the command. The name can be chosen freely and is only used to be displayed in the menu. In the Command field insert the command you want to have executed when selecting the corresponding menu item. Then press the Add button to add the command to your available commands. To edit a command, select it, press the Edit button and press Add after you have finished. To remove a command, select it from the list and press the Remove button. If you want a different order in the contextual submenu, you can use the up and down buttons. 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 (PO file) folder you have selected in the Catalogue Manager. The following strings will be replaced in a command: - @PACKAGE@: The name of the folder without path - @PODIR@: The name of the PO-folder with path - @POTDIR@: The name of the template folder with path + @PACKAGE@: The name of the folder without path + @PODIR@: The name of the PO-folder with path + @POTDIR@: The name of the template folder with path -E.g.: If you want to execute make and then make install you could insert in Make install in the Name field, and make; make install in the Command field. If you then select Commands Make install from the context menu of a folder, the commands listed above will be executed in that folder. +E.g.: If you want to execute make and then make install you could insert in Make install in the Name field, and make; make install in the Command field. If you then select Commands Make install from the context menu of a folder, the commands listed above will be executed in that folder. -File Commands -Here you can insert the commands you want to execute on files from the Catalogue Manager. The commands are then shown in the submenu Commands in the Catalogue Manager's context menu. - -Insert in the Name field the name of the command. The name can be chosen freely and is only used to be displayed in the menu. In the Command field insert the command you want to have executed when selecting the corresponding menu item. Then press the Add button to add the command to your available commands. To edit a command, select it, press the Edit button and press the Add button after you have finished. To remove a command, select it from the list and press the Remove button. If you want a different order in the contextual submenu, you can use the up and down buttons. 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 (PO file) folder, in which the file, you have selected in the Catalogue Manager, is. The following strings will be replaced in a command: +File Commands +Here you can insert the commands you want to execute on files from the Catalogue Manager. The commands are then shown in the submenu Commands in the Catalogue Manager's context menu. + +Insert in the Name field the name of the command. The name can be chosen freely and is only used to be displayed in the menu. In the Command field insert the command you want to have executed when selecting the corresponding menu item. Then press the Add button to add the command to your available commands. To edit a command, select it, press the Edit button and press the Add button after you have finished. To remove a command, select it from the list and press the Remove button. If you want a different order in the contextual submenu, you can use the up and down buttons. 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 (PO file) folder, in which the file, you have selected in the Catalogue Manager, is. The following strings will be replaced in a command: - @PACKAGE@: The name of the file without path and extension - @POFILE@: The name of the PO file with path and extension - @POTFILE@: The name of the corresponding template file with path and extension - @PODIR@: The name of the folder the PO file is in, with path - @POTDIR@: The name of the folder the template file is in, with path + @PACKAGE@: The name of the file without path and extension + @POFILE@: The name of the PO file with path and extension + @POTFILE@: The name of the corresponding template file with path and extension + @PODIR@: The name of the folder the PO file is in, with path + @POTDIR@: The name of the folder the template file is in, with path -For example, if you want to merge the template file into your PO file you could insert Merge in the Name field and msgmerge @POFILE@ @POTFILE@ > @PACKAGE@.new && mv @PACKAGE@.new "@PACKAGE@.po in the Command field. If you then select CommandsMerge from a file's context menu, the PO file will be merged with its template file. +For example, if you want to merge the template file into your PO file you could insert Merge in the Name field and msgmerge @POFILE@ @POTFILE@ > @PACKAGE@.new && mv @PACKAGE@.new "@PACKAGE@.po in the Command field. If you then select CommandsMerge from a file's context menu, the PO file will be merged with its template file. 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 @@ + --> @@ -10,413 +9,157 @@ - + -AlexWalker
alex@x3ja.co.uk
Conversion to British English +AlexWalker
alex@x3ja.co.uk
Conversion to British English -Using &kbabel; +Using &kbabel; -Introduction - -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. - -Every internationalisation-aware program makes available for translation one or more message-catalogue files. The extension of these files is .pot. POT is an acronym for Portable Object Template. - - -Every translator takes a POT file copy and begins translating messages. This file will became a PO file - Portable Object and represents only one language. - -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 PO (Portable Object) file. - -Once all the messages have been translated, the PO file is compiled into a machine-readable binary format, known as a MO (Machine Object) file. These files, which will be stored with a .mo extension, act as a database to minimise the time taken by the applications to look up each translated message. - -This suggests a question: do I need to know what is inside a PO 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 CVS conflicts which occur when a translating process is coordinated by a concurrent version system (see the CVS documentation). &kbabel; can't help you very much if a problem like this arises so a text editor and some knowledge of PO-files are needed. Let's see how a PO file is made. - -PO files consist of pairs of messages—a msgid and a msgstr. 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 PO file for &noatun;, is msgid "Open a Playlist" - -Empty lines and those starting with # 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. - -In many cases the first msgid-msgstr pair in PO file is a fake entry (acting as PO file header) that contains various information about the translated PO file, such as the application name, translating date, translator name and so on. - -Recent versions of &GNU; gettext added another useful i18n feature called plural forms. English uses only singular and one plural form of nouns, ⪚ 1 file and 10 files. This leads many developers to an idea that the world is that simple and they can use messages like Do you want to delete %1 file(s)?, where %1 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. -Plural forms in PO files are here to help. Unfortunately, &kde; developers do not like the plural forms implementation in &GNU; gettext and they have introduced their own format and handling for them. +Introduction + +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. + +Every internationalisation-aware program makes available for translation one or more message-catalogue files. The extension of these files is .pot. POT is an acronym for Portable Object Template. + + +Every translator takes a POT file copy and begins translating messages. This file will became a PO file - Portable Object and represents only one language. + +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 PO (Portable Object) file. + +Once all the messages have been translated, the PO file is compiled into a machine-readable binary format, known as a MO (Machine Object) file. These files, which will be stored with a .mo extension, act as a database to minimise the time taken by the applications to look up each translated message. + +This suggests a question: do I need to know what is inside a PO 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 CVS conflicts which occur when a translating process is coordinated by a concurrent version system (see the CVS documentation). &kbabel; can't help you very much if a problem like this arises so a text editor and some knowledge of PO-files are needed. Let's see how a PO file is made. + +PO files consist of pairs of messages—a msgid and a msgstr. 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 PO file for &noatun;, is msgid "Open a Playlist" + +Empty lines and those starting with # 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. + +In many cases the first msgid-msgstr pair in PO file is a fake entry (acting as PO file header) that contains various information about the translated PO file, such as the application name, translating date, translator name and so on. + +Recent versions of &GNU; gettext added another useful i18n feature called plural forms. English uses only singular and one plural form of nouns, ⪚ 1 file and 10 files. This leads many developers to an idea that the world is that simple and they can use messages like Do you want to delete %1 file(s)?, where %1 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. +Plural forms in PO files are here to help. Unfortunately, &kde; developers do not like the plural forms implementation in &GNU; gettext and they have introduced their own format and handling for them. -Editor +Editor -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. +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. -The upper-left edit box is read-only and contains the current msgid field from the opened PO-file and its English text. +The upper-left edit box is read-only and contains the current msgid field from the opened PO-file and its English text. -The bottom-left edit box contains the msgstr field related to the msgid shown and here you can edit the translated text. +The bottom-left edit box contains the msgstr field related to the msgid shown and here you can edit the translated text. -The top-right part of the window is a comments panel where you can view the comments added for entry currently being edited. +The top-right part of the window is a comments panel where you can view the comments added for entry currently being edited. -It can be used: +It can be used: -to find out how the current message is treated by the application (c-formatted or simple) -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 LyX project) -when you need to know which file a message is from because you want to report a spelling mistake in the original English string. +to find out how the current message is treated by the application (c-formatted or simple) +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 LyX project) +when you need to know which file a message is from because you want to report a spelling mistake in the original English string. -Screenshot of &kbabel; +Screenshot of &kbabel; -Screenshot of &kbabel; +Screenshot of &kbabel; -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. +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. -More &kbabel; Features +More &kbabel; Features -Each msgid entry can be in three states: +Each msgid entry can be in three states: - untranslated + untranslated - there is no translated text currently associated with the msgstr + there is no translated text currently associated with the msgstr - fuzzy + fuzzy - msgmerge 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. + msgmerge 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. - translated + translated - the msgid is the completed translated form of the msgstr + the msgid is the completed translated form of the msgstr -The state of the current entry is indicated by two LEDs. Depending on your configuration these can either be in the status bar or above the translated string edit box. Both have a customisable colour (to reflect your visual requirements or taste). Please read the Preferences section to see how you can adjust these settings. +The state of the current entry is indicated by two LEDs. Depending on your configuration these can either be in the status bar or above the translated string edit box. Both have a customisable colour (to reflect your visual requirements or taste). Please read the Preferences section to see how you can adjust these settings. -Advanced Translation +Advanced Translation -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. +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. -Navigation in PO-file -&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 validation checking or validation done by msgfmt. And, of course, &kbabel; supports browsing the history of visited messages with Forward/Back, like in &konqueror;. -All commands for navigation are in Go menu. +Navigation in PO-file +&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 validation checking or validation done by msgfmt. And, of course, &kbabel; supports browsing the history of visited messages with Forward/Back, like in &konqueror;. +All commands for navigation are in Go menu. -Page Up -Move to the previous message +Page Up +Move to the previous message -Page Down -Move to the next message +Page Down +Move to the next message -&Ctrl;Page Up -Move to the previous fuzzy message +&Ctrl;Page Up +Move to the previous fuzzy message -&Ctrl;Page Down -Move to the next fuzzy message +&Ctrl;Page Down +Move to the next fuzzy message -&Alt;Page Up -Move to the previous untranslated message +&Alt;Page Up +Move to the previous untranslated message -&Alt;Page Down -Move to the next untranslated message +&Alt;Page Down +Move to the next untranslated message -&Shift;Page Up -Move to the previous error message +&Shift;Page Up +Move to the previous error message -&Shift;Page Down -Move to the next error message +&Shift;Page Down +Move to the next error message -&Ctrl;&Shift;Page Up -Move to the previous fuzzy or untranslated message +&Ctrl;&Shift;Page Up +Move to the previous fuzzy or untranslated message -&Ctrl;&Shift;Page Down -Move to the next fuzzy or untranslated message +&Ctrl;&Shift;Page Down +Move to the next fuzzy or untranslated message @@ -424,138 +167,47 @@ -Clever editing -Clever editing means that the editor will help you easily edit the translation while taking into account specials of the PO format. It will correctly escape as necessary. -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 msgstr is a single line.) If you want insert a real end of the line, you need to insert \n. But most of translators do not realize, that a new line in msgstr 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. -The table below summarises clever editing features. +Clever editing +Clever editing means that the editor will help you easily edit the translation while taking into account specials of the PO format. It will correctly escape as necessary. +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 msgstr is a single line.) If you want insert a real end of the line, you need to insert \n. But most of translators do not realize, that a new line in msgstr 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. +The table below summarises clever editing features. -Tab -Insert \t +Tab +Insert \t -" -Insert \" +" +Insert \" -Enter -If the last character before cursor is not a space, insert one space. Then start a new line. - -&Ctrl;Enter -Start a new line without any additional logic +Enter +If the last character before cursor is not a space, insert one space. Then start a new line. + +&Ctrl;Enter +Start a new line without any additional logic -&Shift;Enter -Insert \n and start a new line +&Shift;Enter +Insert \n and start a new line -If you want to see where are spaces, you can turn on Highlight background and/or Mark whitespaces with points in preferences dialogue on tab Edit Appearance. +If you want to see where are spaces, you can turn on Highlight background and/or Mark whitespaces with points in preferences dialogue on tab Edit Appearance. -Automatic translation -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 ToolsRough Translation and &kbabel; will present the following dialogue: +Automatic translation +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 ToolsRough Translation and &kbabel; will present the following dialogue: -Rough translation dialogue +Rough translation dialogue @@ -563,298 +215,122 @@ -In the dialogue, you should specify what to translate and choose the sources for the old translations. -At the top of the What to translate frame are three checkboxes (Untranslated entries, Fuzzy entries , Translated entries) 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. -The exact matching for msgids will always be used for rough translation. However, you can add more strategies, &ie; Allow fuzzy translation (slow) and Allow single word translation. Both of these additional strategies must be supported by the sources used (see below). There is no specification, what does fuzzy translation mean, but the purpose is quite obvious. Single word translation is suitable for only some of the languages. &kbabel; will try to translate each word in msgid separately and then put the translated words (or phrases) in the same order in msgstr . -As a source for rough translation, any dictionary module available can be used. There is a list of Don't use modules and Use modules. Modules are used in the order in the Use 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 Move Up and Move Down buttons. -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. Mark changed entries as fuzzy allows you to turn off this automatic fuzzy marking, but you will need to confirm this. -If you have set all the options to suit your needs, push Start to automatically translate messages. You can follow the progress bar and in case, there is always the Stop button. +In the dialogue, you should specify what to translate and choose the sources for the old translations. +At the top of the What to translate frame are three checkboxes (Untranslated entries, Fuzzy entries , Translated entries) 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. +The exact matching for msgids will always be used for rough translation. However, you can add more strategies, &ie; Allow fuzzy translation (slow) and Allow single word translation. Both of these additional strategies must be supported by the sources used (see below). There is no specification, what does fuzzy translation mean, but the purpose is quite obvious. Single word translation is suitable for only some of the languages. &kbabel; will try to translate each word in msgid separately and then put the translated words (or phrases) in the same order in msgstr . +As a source for rough translation, any dictionary module available can be used. There is a list of Don't use modules and Use modules. Modules are used in the order in the Use 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 Move Up and Move Down buttons. +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. Mark changed entries as fuzzy allows you to turn off this automatic fuzzy marking, but you will need to confirm this. +If you have set all the options to suit your needs, push Start to automatically translate messages. You can follow the progress bar and in case, there is always the Stop button. -Validate your translation -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. -Checks can be done at each change of the translated text. These are called automatic checks and they can be turned on in the &kbabel; configuration dialogue. Automatic checking of syntax is possible at each saving of the file. -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 Tools Validation. Then the check is performed for all messages in the file and faulty ones are marked as errors. +Validate your translation +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. +Checks can be done at each change of the translated text. These are called automatic checks and they can be turned on in the &kbabel; configuration dialogue. Automatic checking of syntax is possible at each saving of the file. +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 Tools Validation. Then the check is performed for all messages in the file and faulty ones are marked as errors. - Check Syntax + Check Syntax - This invokes msgfmt to check validity of the PO file as seen by gettext package. It will show the result of the command and mark error msgstrs. + This invokes msgfmt to check validity of the PO file as seen by gettext package. It will show the result of the command and mark error msgstrs. - Check Arguments + Check Arguments - 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 msgid and msgstr. They must match. + 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 msgid and msgstr. They must match. - Check Accelerators + Check Accelerators - &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 Preferences on Misc tab. + &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 Preferences on Misc tab. - Look for Translated Context Info + Look for Translated Context Info - 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 msgid after the special sequence :_. 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. + 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 msgid after the special sequence :_. 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. - Check Plural Forms + Check Plural Forms - If the msgid is specified as a plural form, the translation has to contain the correct number of translations separated by \n. The correct number depends on the language of translation and is specified on Identity tab in Preferences dialogue. This is implemented only for &kde; at the moment. + If the msgid is specified as a plural form, the translation has to contain the correct number of translations separated by \n. The correct number depends on the language of translation and is specified on Identity tab in Preferences dialogue. This is implemented only for &kde; at the moment. - Check Equations + Check Equations - Equations are special format of msgid typically used in .desktop files. And because your translations will be merged back to these files, msgstr must use this special format as well. This means that the translation must start (up to the first occurrence of = with the same text as the original message, ⪚ Name=. + Equations are special format of msgid typically used in .desktop files. And because your translations will be merged back to these files, msgstr must use this special format as well. This means that the translation must start (up to the first occurrence of = with the same text as the original message, ⪚ Name=. -Spellchecking the translation -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 the &kbabel; configuration dialogue. Spell checking itself can be found in ToolsSpelling submenu. You can use a number of modes for spell checking: +Spellchecking the translation +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 the &kbabel; configuration dialogue. Spell checking itself can be found in ToolsSpelling submenu. You can use a number of modes for spell checking: - Spell check... + Spell check... - 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 &Ctrl;I . + 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 &Ctrl;I . - Check All... + Check All... - Spellcheck all messages in the file. + Spellcheck all messages in the file. - Check from Cursor Position... + Check from Cursor Position... - Start spellchecking at the position in the current message and progress towards the end of the file. + Start spellchecking at the position in the current message and progress towards the end of the file. - Check Current... + Check Current... - Spellcheck the current message only. + Spellcheck the current message only. - Check Selected Text... + Check Selected Text... - If there is a selected text in msgstr editor, this option is available and will spellcheck this text only. + If there is a selected text in msgstr editor, this option is available and will spellcheck this text only. -Translating &XML;, <acronym ->HTML</acronym ->, ... -Markup languages are used more and more in &GUI;. &kde; project also uses PO-files for translating DocBook documentation files (which is also a markup language). &kbabel; contains quite a lot of functionality to support this trend. +Translating &XML;, <acronym>HTML</acronym>, ... +Markup languages are used more and more in &GUI;. &kde; project also uses PO-files for translating DocBook documentation files (which is also a markup language). &kbabel; contains quite a lot of functionality to support this trend. -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 diff feature described in the following section. +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 diff feature described in the following section. -The current version of &kbabel; is capable to find out which tags are used in msgid and provide an easy access to them using following actions from the Edit: +The current version of &kbabel; is capable to find out which tags are used in msgid and provide an easy access to them using following actions from the Edit: - Insert Next Tag + Insert Next Tag - 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. + 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. - Edit Insert Tag + Edit Insert Tag - 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. + 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. @@ -862,142 +338,50 @@ -Showing the difference -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 msgid 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.) -To help, &kbabel; can be asked to lookup the original msgid and to show the difference. The changes are graphically displayed in the Original String window. The exact method can be set in the &kbabel; configuration dialogue. Tools Diff Show Diff will show the differences found. To see the current text without the mixture of original text and differences, use Tools Diff Show Original Text . -You can turn automatic lookup of difference on and off by choosing Tools Diff Diff Mode . When the diff mode is on, difference searching starts when you go to another message. -As always, you can use different sources for finding the old version of the text, all being set in in &kbabel; configuration dialogue: +Showing the difference +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 msgid 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.) +To help, &kbabel; can be asked to lookup the original msgid and to show the difference. The changes are graphically displayed in the Original String window. The exact method can be set in the &kbabel; configuration dialogue. Tools Diff Show Diff will show the differences found. To see the current text without the mixture of original text and differences, use Tools Diff Show Original Text . +You can turn automatic lookup of difference on and off by choosing Tools Diff Diff Mode . When the diff mode is on, difference searching starts when you go to another message. +As always, you can use different sources for finding the old version of the text, all being set in in &kbabel; configuration dialogue: - Translation Database + Translation Database - 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 Translation Database configuration dialogue. This mode can be turned on by Use messages from Translation Database. + 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 Translation Database configuration dialogue. This mode can be turned on by Use messages from Translation Database. - Tree of the old files + Tree of the old files - This will be used only if searching in Translation Database is turned off. By setting Base folder for diff files 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. + This will be used only if searching in Translation Database is turned off. By setting Base folder for diff files 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. - Manually chosen file + Manually chosen file - If the previous possibility does not work, correctly, you can always set the difference file manually by choosing ToolsDiff Open File for Diff. + If the previous possibility does not work, correctly, you can always set the difference file manually by choosing ToolsDiff Open File for Diff. -The difference lookup is not always accurate, because the PO-file does not contain any reference to the original message. +The difference lookup is not always accurate, because the PO-file does not contain any reference to the original message. -Plural Forms -Because plural forms are quite a complicated issue, we devote a special section for their suport in &kbabel;. -&kbabel; can read the &GNU; plural forms only, but cannot edit them. It only supports the &kde; version of plural forms at the moment. -Every language to which &kde; is translated must have set a correct number of plural forms. This is done by translating an entry in tdelibs.po. The number is set by selecting the name of a language, which uses the same number and rules 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 tdecore/tdelocale.cpp. -&kde; plural forms are denoted by comment _: containing the %n 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. -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 \n. For example, Selected %n files translated to Slovak would be: -Vybraný %n súbor\n +Plural Forms +Because plural forms are quite a complicated issue, we devote a special section for their suport in &kbabel;. +&kbabel; can read the &GNU; plural forms only, but cannot edit them. It only supports the &kde; version of plural forms at the moment. +Every language to which &kde; is translated must have set a correct number of plural forms. This is done by translating an entry in tdelibs.po. The number is set by selecting the name of a language, which uses the same number and rules 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 tdecore/tdelocale.cpp. +&kde; plural forms are denoted by comment _: containing the %n 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. +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 \n. For example, Selected %n files translated to Slovak would be: +Vybraný %n súbor\n Vybrané %n súbory\n Vybraných %n súborov -To check if your translation contains the correct number of plural forms, use the Tools Validation Check Plural Forms (KDE only) menu. +To check if your translation contains the correct number of plural forms, use the Tools Validation Check Plural Forms (KDE only) menu. 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 @@ -The &kbugbuster; Handbook +The &kbugbuster; Handbook -
+
-MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English +MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English -&FDLNotice; +&FDLNotice; -2002-03-31 -0.00.00 +2002-03-31 +0.00.00 -&kbugbuster; is part of the tdesdk package. +&kbugbuster; is part of the tdesdk package. -KDE -kbugbuster +KDE +kbugbuster - Introduction The documentation for &kappname; was not finished when &kde; was installed on this computer. If you need help, please check The &kde; Website for updates, or by submitting your question to The &kde; User Mailing list. The &kde; Team &underFDL; + Introduction The documentation for &kappname; was not finished when &kde; was installed on this computer. If you need help, please check The &kde; Website for updates, or by submitting your question to The &kde; User Mailing list. The &kde; Team &underFDL; &documentation.index; 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 @@ -The &kompare; Handbook +The &kompare; Handbook -
+
-MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English +MalcolmHunter
malcolm.hunter@gmx.co.uk
Conversion to British English -&FDLNotice; +&FDLNotice; -2002-12-16 -0.00.00 +2002-12-16 +0.00.00 -&kompare; is a program to view the differences between files. +&kompare; is a program to view the differences between files. -KDE -Kompare +KDE +Kompare - Introduction The documentation for &kappname; was not finished when &kde; was installed on this computer. If you need help, please check The &kde; Website for updates, or by submitting your question to The &kde; User Mailing list. The &kde; Team &underFDL; + Introduction The documentation for &kappname; was not finished when &kde; was installed on this computer. If you need help, please check The &kde; Website for updates, or by submitting your question to The &kde; User Mailing list. The &kde; Team &underFDL; &documentation.index; 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 @@ KCachegrind'> - Cachegrind"> - Calltree"> - Callgrind"> - Valgrind"> - OProfile"> + KCachegrind'> + Cachegrind"> + Calltree"> + Callgrind"> + Valgrind"> + OProfile"> @@ -29,167 +17,96 @@ -The &tdecachegrind; Handbook +The &tdecachegrind; Handbook -Josef Weidendorfer
Josef.Weidendorfer@gmx.de
+Josef Weidendorfer
Josef.Weidendorfer@gmx.de
 -AndrewColes
andrew_coles@yahoo.co.uk
Conversion to British English +AndrewColes
andrew_coles@yahoo.co.uk
Conversion to British English -2002-2004 -Josef Weidendorfer +2002-2004 +Josef Weidendorfer -&FDLNotice; +&FDLNotice; -2004-07-27 -0.4.6 +2004-07-27 +0.4.6 -&tdecachegrind; is a profile data visualisation tool, written using the &kde; environment. +&tdecachegrind; is a profile data visualisation tool, written using the &kde; environment. -KDE -tdesdk -Cachegrind -Callgrind -Valgrind -Profiling +KDE +tdesdk +Cachegrind +Callgrind +Valgrind +Profiling -Introduction +Introduction -&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. +&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. -Profiling +Profiling -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. +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. -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. +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. -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. +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. -Profiling Methods +Profiling Methods -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. +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. -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. +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. -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. +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. -Profiling Tools - -Most known is the GCC profiling tool gprof: One needs to compile the program with option ; running the program generates a file gmon.out, which can be transformed into human-readable form with gprof. 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. - -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). - -&oprofile; is a system-wide profiling tool for Linux using Sampling. - -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. - -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. - -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. +Profiling Tools + +Most known is the GCC profiling tool gprof: One needs to compile the program with option ; running the program generates a file gmon.out, which can be transformed into human-readable form with gprof. 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. + +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). + +&oprofile; is a system-wide profiling tool for Linux using Sampling. + +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. + +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. + +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. -Visualisation +Visualisation -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. +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. -&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. +&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. -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 -a call-graph view, which shows a section of the call graph around the selected function, +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 +a call-graph view, which shows a section of the call graph around the selected function, -a tree-map view, which allows nested-call relations to be visualised, together with inclusive cost metric for fast visual detection of problematic functions, +a tree-map view, which allows nested-call relations to be visualised, together with inclusive cost metric for fast visual detection of problematic functions, -source code and disassembler annotation views, allowing to see details of cost related to source lines and assembler instructions. +source code and disassembler annotation views, allowing to see details of cost related to source lines and assembler instructions. @@ -198,409 +115,193 @@ -Using &tdecachegrind; +Using &tdecachegrind; -Generate Data to Visualise +Generate Data to Visualise -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. +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. -&callgrind; - -&callgrind; is available from http://tdecachegrind.sf.net. Note that it previously was called &calltree;, but that name was misleading. - -Most common use is to prefix the command line to start your application with callgrind, like in
callgrind myprogram myargs
At program termination, a file callgrind.out.pid will be generated which can be loaded into &tdecachegrind;. - -More advanced use is to dump out profile data whenever a given function of your application is called. E.g. for konqueror, 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 KonqMainWindow::slotReload. Use
callgrind --dump-before=KonqMainWindow::slotReload konqueror
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. +&callgrind; + +&callgrind; is available from http://tdecachegrind.sf.net. Note that it previously was called &calltree;, but that name was misleading. + +Most common use is to prefix the command line to start your application with callgrind, like in
callgrind myprogram myargs
At program termination, a file callgrind.out.pid will be generated which can be loaded into &tdecachegrind;. + +More advanced use is to dump out profile data whenever a given function of your application is called. E.g. for konqueror, 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 KonqMainWindow::slotReload. Use
callgrind --dump-before=KonqMainWindow::slotReload konqueror
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. -&oprofile; - -&oprofile; is available from http://oprofile.sf.net. 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). - -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 oprof_start or the command-line tool opcontrol. Standard configuration should be timer mode (TBS, see introduction). To start the measurement, run opcontrol -s. Then run the application you are interested in and, afterwards, do a opcontrol -d. This will write out the measurement results into files under directory /var/lib/oprofile/samples/. To be able to visualise the data in &tdecachegrind;, do in an empty directory:
opreport -gdf | op2callgrind
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. +&oprofile; + +&oprofile; is available from http://oprofile.sf.net. 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). + +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 oprof_start or the command-line tool opcontrol. Standard configuration should be timer mode (TBS, see introduction). To start the measurement, run opcontrol -s. Then run the application you are interested in and, afterwards, do a opcontrol -d. This will write out the measurement results into files under directory /var/lib/oprofile/samples/. To be able to visualise the data in &tdecachegrind;, do in an empty directory:
opreport -gdf | op2callgrind
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. -User Interface Basics - -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. - -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). - -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 main 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. - -To explore the GUI further, in addition to this manual, also have a look at the documentation section on the web site http://tdecachegrind.sf.net. Also, every widget in &tdecachegrind; has What's this help. +User Interface Basics + +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. + +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). + +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 main 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. + +To explore the GUI further, in addition to this manual, also have a look at the documentation section on the web site http://tdecachegrind.sf.net. Also, every widget in &tdecachegrind; has What's this help. -Basic Concepts +Basic Concepts -This chapter explains some concepts of the &tdecachegrind;, and introduces terms used in the interface. +This chapter explains some concepts of the &tdecachegrind;, and introduces terms used in the interface. -The Data Model for Profile Data +The Data Model for Profile Data -Cost Entities - -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. - -The cost entities known to KCachegrind are given in the following. Simple Positions: Instruction. An assembler instruction at a specified address. 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 "???". 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 "???". Binary Object. All functions whose code is inside the range of a given binary object, either the main executable or a shared library. Source File. All functions whose first instruction is mapped to a line of the given source file. 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. Profile Part. Some time section of a profile run, with a given thread ID, process ID, and command line executed. 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. - -Positions tuples: Call from instruction address to target function. Call from source line to target function. Call from source function to target function. (Un)conditional Jump from source to target instruction. (Un)conditional Jump from source to target line. 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. +Cost Entities + +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. + +The cost entities known to KCachegrind are given in the following. Simple Positions: Instruction. An assembler instruction at a specified address. 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 "???". 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 "???". Binary Object. All functions whose code is inside the range of a given binary object, either the main executable or a shared library. Source File. All functions whose first instruction is mapped to a line of the given source file. 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. Profile Part. Some time section of a profile run, with a given thread ID, process ID, and command line executed. 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. + +Positions tuples: Call from instruction address to target function. Call from source line to target function. Call from source function to target function. (Un)conditional Jump from source to target instruction. (Un)conditional Jump from source to target line. 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. -Event Types +Event Types -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. -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. +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. +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. -Visualisation State - -The Visualisation state of a KCachegrind window includes: the primary and secondary event type chosen for display, the function grouping (used in the Function Profile list and entity colouring), the profile parts whose costs are to be included in visualisation, an active cost entity (e.g. a function selected from the function profile dockable), a selected cost entity. This state influences visualisations. -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). -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. +Visualisation State + +The Visualisation state of a KCachegrind window includes: the primary and secondary event type chosen for display, the function grouping (used in the Function Profile list and entity colouring), the profile parts whose costs are to be included in visualisation, an active cost entity (e.g. a function selected from the function profile dockable), a selected cost entity. This state influences visualisations. +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). +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. -Parts of the GUI +Parts of the GUI -Sidedocks -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. -Function Profile. The Function Profile is a list of functions showing inclusive and exclusive cost, call count, name and position of functions. -Parts Overview -Call Stack +Sidedocks +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. +Function Profile. The Function Profile is a list of functions showing inclusive and exclusive cost, call count, name and position of functions. +Parts Overview +Call Stack -Visualisation Area -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. +Visualisation Area +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. -Areas of a Tab View -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. +Areas of a Tab View +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. -Synchronised Visualisation via Selected Entity in a Tab View -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. +Synchronised Visualisation via Selected Entity in a Tab View +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. -Synchronisation between Tab Views -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. +Synchronisation between Tab Views +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. -Layouts -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. +Layouts +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. -Sidedocks +Sidedocks -Flat Profile -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. -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. +Flat Profile +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. +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. -Parts Overview -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. -The parts are further subdivided: there is a partitioning and an inclusive cost split mode: -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. -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. +Parts Overview +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. +The parts are further subdivided: there is a partitioning and an inclusive cost split mode: +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. +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. -Call Stack -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. -The 'Cost' and 'Calls' columns show the cost used for all calls from the function in the line above. +Call Stack +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. +The 'Cost' and 'Calls' columns show the cost used for all calls from the function in the line above. -Visualisations +Visualisations -Event Types -This list shows all cost types available and the corresponding self and inclusive cost of the current active function for that event type. -By choosing an event type from the list, you change the type of costs shown all over KCachegrind to be the selected one. +Event Types +This list shows all cost types available and the corresponding self and inclusive cost of the current active function for that event type. +By choosing an event type from the list, you change the type of costs shown all over KCachegrind to be the selected one. -Call Lists -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. -Call list views include: -Direct Callers -Direct Callees -All Callers -All Callees +Call Lists +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. +Call list views include: +Direct Callers +Direct Callees +All Callers +All Callees -Maps -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). -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. -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. -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. +Maps +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). +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. +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. +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. -Call Graph -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. -For cycles, blue call arrows indicate that this is an artificial call added for correct drawing which actually never happened. -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. +Call Graph +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. +For cycles, blue call arrows indicate that this is an artificial call added for correct drawing which actually never happened. +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. -Annotations -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. -Select such a call information line to activate the call destination. +Annotations +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. +Select such a call information line to activate the call destination. @@ -608,128 +309,42 @@ -Command Reference +Command Reference -The main &tdecachegrind; window - +The main &tdecachegrind; window + -The <guimenu ->File</guimenu -> Menu +The <guimenu>File</guimenu> Menu - &Ctrl;N File New - Opens an empty toplevel window into which you can load profile data. This action is not really needed, as File/Open will give you a new toplevel window when the current one shows already some data. + &Ctrl;N File New + Opens an empty toplevel window into which you can load profile data. This action is not really needed, as File/Open will give you a new toplevel window when the current one shows already some data. - &Ctrl;O File Open - Pops up the File Open Dialogue to choose a profile data file to be loaded. 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. -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. -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. + &Ctrl;O File Open + Pops up the File Open Dialogue to choose a profile data file to be loaded. 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. +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. +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. -File Add - Adds a profile data file to the current window. 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. +File Add + Adds a profile data file to the current window. 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. -File Reload - Reload the profile data. This is most interesting after another profile data file was generated for an already loaded application run. +File Reload + Reload the profile data. This is most interesting after another profile data file was generated for an already loaded application run. - &Ctrl;Q File Quit -Quits &kappname; + &Ctrl;Q File Quit +Quits &kappname; @@ -737,96 +352,33 @@ -The <guimenu ->View</guimenu -> Menu +The <guimenu>View</guimenu> Menu -View Primary Event Type -(To-do) +View Primary Event Type +(To-do) -View Secondary Event Type -(To-do) +View Secondary Event Type +(To-do) -View Grouping -(To-do) +View Grouping +(To-do) -View Layout -(To-do) +View Layout +(To-do) -View Split -(To-do) +View Split +(To-do) @@ -839,56 +391,44 @@ -Questions and Answers +Questions and Answers &reporting.bugs; &updating.documentation; -What is &tdecachegrind; for? I have no idea. +What is &tdecachegrind; for? I have no idea. -&tdecachegrind; is a helpful at a later stage in software development, called Profiling. If you don't develop applications, you don't need &tdecachegrind;. +&tdecachegrind; is a helpful at a later stage in software development, called Profiling. If you don't develop applications, you don't need &tdecachegrind;. -What is the difference between 'Incl.' and 'Self' ? +What is the difference between 'Incl.' and 'Self' ? -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. -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. +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. +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. -The toolbar/menubar of my KCachegrind looks so spartanic. Is this normal? +The toolbar/menubar of my KCachegrind looks so spartanic. Is this normal? -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 configure --prefix=/opt/kde3; make install. If you choose another directory like $HOME/kde, you should set the environment variable TDEDIR to this directory before running KCachegrind. +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 configure --prefix=/opt/kde3; make install. If you choose another directory like $HOME/kde, you should set the environment variable TDEDIR to this directory before running KCachegrind. -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% ? +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% ? -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. +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. @@ -897,59 +437,21 @@ -Glossary - -The following is a mixed list of terms. -Profiling: The process of collecting statistical information about runtime characteristics of program runs. -Tracing: The process of supervising a program run and storing events happening sorted by a timestap in a output file, the Trace. -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. -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. -Profile Data Part (incorrectly used also: Trace Part): Data from a profile data file. -Profile Experiment: A program run supervised by a profiling tool, producing possibly multiple profile data files from parts and/or threads of the run. -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. -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). -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. -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. -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. -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. +Glossary + +The following is a mixed list of terms. +Profiling: The process of collecting statistical information about runtime characteristics of program runs. +Tracing: The process of supervising a program run and storing events happening sorted by a timestap in a output file, the Trace. +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. +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. +Profile Data Part (incorrectly used also: Trace Part): Data from a profile data file. +Profile Experiment: A program run supervised by a profiling tool, producing possibly multiple profile data files from parts and/or threads of the run. +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. +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). +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. +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. +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. +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. @@ -957,52 +459,36 @@ -Credits and License +Credits and License -&kappname; -Thanks to Julian Seward for his excellent &valgrind;, and Nicholas Nethercote for the &cachegrind; addition. Without these programs, KCachegrind would not exist. Some ideas for this &GUI; were from them, too. -And thanks for all the bug reports/suggestions from different users. +&kappname; +Thanks to Julian Seward for his excellent &valgrind;, and Nicholas Nethercote for the &cachegrind; addition. Without these programs, KCachegrind would not exist. Some ideas for this &GUI; were from them, too. +And thanks for all the bug reports/suggestions from different users. &underFDL; -Installation +Installation -How to obtain &tdecachegrind; +How to obtain &tdecachegrind; -&tdecachegrind; is part of the &package; package of &kde;. For less supported interim releases, &callgrind; and further documentation, see the homepage at http://tdecachegrind.sf.net. Look there for further installation and compile instructions. +&tdecachegrind; is part of the &package; package of &kde;. For less supported interim releases, &callgrind; and further documentation, see the homepage at http://tdecachegrind.sf.net. Look there for further installation and compile instructions. -Requirements +Requirements -In order to successfully use &tdecachegrind;, you need &kde; 3.x. For generating profile data, &cachegrind; or &calltree;/&callgrind; is recommend. +In order to successfully use &tdecachegrind;, you need &kde; 3.x. For generating profile data, &cachegrind; or &calltree;/&callgrind; is recommend. -Compilation and Installation +Compilation and Installation &install.compile.documentation; -Configuration +Configuration -All configuration options are either in the configuration dialogue or in the context popup menus of the visualisations. +All configuration options are either in the configuration dialogue or in the context popup menus of the visualisations. 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 @@ -Authors and History -This project was started by Paul Hensgen as one of his University projects. The original name of the application was UML Modeller. Paul did all the development until the end of 2001 when the program reached version 1.0. -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 UML Modeller, 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. -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 &UML; Modeller, to &umbrello;. There are several reasons for the change of names, the most important ones being that just uml — 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 Umbrello is a much cooler name. -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;: +Authors and History +This project was started by Paul Hensgen as one of his University projects. The original name of the application was UML Modeller. Paul did all the development until the end of 2001 when the program reached version 1.0. +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 UML Modeller, 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. +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 &UML; Modeller, to &umbrello;. There are several reasons for the change of names, the most important ones being that just uml — 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 Umbrello is a much cooler name. +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;: -Reporting bugs or improvements suggestions -Fixing bugs or adding features -Writing good documentation or translating it to other languages -And of course...coding with us! +Reporting bugs or improvements suggestions +Fixing bugs or adding features +Writing good documentation or translating it to other languages +And of course...coding with us! -As you see, there are many ways in which you can contribute. All of them are very important and everyone is welcome to participate. -The &umbrello; developers can be reached at uml-devel@lists.sourceforge.net. +As you see, there are many ways in which you can contribute. All of them are very important and everyone is welcome to participate. +The &umbrello; developers can be reached at uml-devel@lists.sourceforge.net. 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 @@ -Code Import and Code Generation -&umbrello; is a &UML; modelling tool, and as such its main purpose is to help you in the analysis and design of your systems. However, to make the transition between your design and your implementation, &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. +Code Import and Code Generation +&umbrello; is a &UML; modelling tool, and as such its main purpose is to help you in the analysis and design of your systems. However, to make the transition between your design and your implementation, &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. -Code Generation -&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 fill in the blanks by providing the functionality of your classes' operations. -&umbrello; 1.2 comes with code generation support for ActionScript, Ada, C++, CORBA IDL, &Java;, JavaScript, PHP, Perl, Python, SQL and XMLSchema. +Code Generation +&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 fill in the blanks by providing the functionality of your classes' operations. +&umbrello; 1.2 comes with code generation support for ActionScript, Ada, C++, CORBA IDL, &Java;, JavaScript, PHP, Perl, Python, SQL and XMLSchema. -Generating Code -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 Code Generation Wizard entry from the Code menu to start a wizard which will guide you through the code generation process. -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. -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: +Generating Code +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 Code Generation Wizard entry from the Code menu to start a wizard which will guide you through the code generation process. +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. +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: -Code Generation Options +Code Generation Options - Options for the Code Generation in &umbrello; + Options for the Code Generation in &umbrello; - Options for the Code Generation in &umbrello; + Options for the Code Generation in &umbrello; -Generation Options +Generation Options -Code Verbosity -The option Write documentation comments even if empty 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 Doxygen 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. -Write comments for sections even if section is empty causes &umbrello; to write comments in the source code to delimit the different sections of a class. For example public methods or Attributes 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 protected methods even if there are no protected methods in your class. +Code Verbosity +The option Write documentation comments even if empty 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 Doxygen 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. +Write comments for sections even if section is empty causes &umbrello; to write comments in the source code to delimit the different sections of a class. For example public methods or Attributes 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 protected methods even if there are no protected methods in your class. -Folders -Write all generated files to folder. Here you should select the folder where you want &umbrello; to put the generated sources. -The Include heading files from folder 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. +Folders +Write all generated files to folder. Here you should select the folder where you want &umbrello; to put the generated sources. +The Include heading files from folder 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. -Overwrite Policy +Overwrite Policy -This option tells &umbrello; what to do if the file it wants to create already exists in the destination folder. &umbrello; cannot modify existing source files, 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. +This option tells &umbrello; what to do if the file it wants to create already exists in the destination folder. &umbrello; cannot modify existing source files, 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. -Language -&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. +Language +&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. - + -Generation Wizard Generation -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. -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 Code Generation section of the &umbrello; settings, available at SettingsConfigure &umbrello;... -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 Generate All Code 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). +Generation Wizard Generation +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. +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 Code Generation section of the &umbrello; settings, available at SettingsConfigure &umbrello;... +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 Generate All Code 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). - - + + -Code Import -&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. -To import classes into your Model, select the entry Import Classes... from the Code 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. +Code Import +&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. +To import classes into your Model, select the entry Import Classes... from the Code 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. -Code Import +Code Import - Menu for importing source code in &umbrello; + Menu for importing source code in &umbrello; - Menu for importing source code in &umbrello; + Menu for importing source code in &umbrello; - + 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 @@ -Copyright +Copyright -Copyright 2001, Paul Hensgen -Copyright 2002, 2003 The &umbrello; Authors. See http://uml.sf.net/developers.php for more information +Copyright 2001, Paul Hensgen +Copyright 2002, 2003 The &umbrello; Authors. See http://uml.sf.net/developers.php for more information &underFDL; &underGPL; 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 @@ Umbrello &UML; Modeller"> + Umbrello &UML; Modeller"> - UML"> + UML"> @@ -17,59 +13,43 @@ - + ]> -&umbrello; Handbook +&umbrello; Handbook -&umbrello; Authors +&umbrello; Authors -2001 -Paul Hensgen +2001 +Paul Hensgen -2002, 2003 -&umbrello; Authors +2002, 2003 +&umbrello; Authors -2003-10-15 -1.2 +2003-10-15 +1.2 -&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. +&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. -KDE -UML -modelling -diagrams -software development -development +KDE +UML +modelling +diagrams +software development +development 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 @@ -Introduction +Introduction -&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. -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. -&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: +&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. +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. +&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: -Class Diagram -Sequence Diagram -Collaboration Diagram -Use Case Diagram -State Diagram -Activity Diagram -Component Diagram -Deployment Diagram +Class Diagram +Sequence Diagram +Collaboration Diagram +Use Case Diagram +State Diagram +Activity Diagram +Component Diagram +Deployment Diagram -More information about &UML; can be found at the website of OMG, http://www.omg.org who create the &UML; standard. -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 uml-devel@lists.sourceforge.net or http://bugs.kde.org. +More information about &UML; can be found at the website of OMG, http://www.omg.org who create the &UML; standard. +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 uml-devel@lists.sourceforge.net or http://bugs.kde.org. 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 @@ -Other Features - -Other &umbrello; Features -This chapter will briefly explain some other features &umbrello; offers you. +Other Features + +Other &umbrello; Features +This chapter will briefly explain some other features &umbrello; offers you. -Copying objects as PNG images -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 (&Ctrl;C, or using the menu), then open a &kword; document (or any program into which you can paste images) and select Paste. This is a great feature to export parts of your diagram as simple pictures. +Copying objects as PNG images +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 (&Ctrl;C, or using the menu), then open a &kword; document (or any program into which you can paste images) and select Paste. This is a great feature to export parts of your diagram as simple pictures. -Exporting to an Image -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 Export as Picture... from the Diagram menu. +Exporting to an Image +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 Export as Picture... from the Diagram menu. -Printing -&umbrello; allows you to print individual diagrams. Press the Print button on the application toolbar or selecting the Print option from the File menu will give you a standard &kde; Print dialogue from where you can print your diagrams. +Printing +&umbrello; allows you to print individual diagrams. Press the Print button on the application toolbar or selecting the Print option from the File menu will give you a standard &kde; Print dialogue from where you can print your diagrams. -Logical Folders -To better organise your model, especially for larger projects, you can create logical folders in the Tree View. Just select the option NewFolder 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. +Logical Folders +To better organise your model, especially for larger projects, you can create logical folders in the Tree View. Just select the option NewFolder 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. -Organising your Model with Folders +Organising your Model with Folders - Organising a Model with Logical Folders in &umbrello; + Organising a Model with Logical Folders in &umbrello; - Organising a Model with Logical Folders in &umbrello; + Organising a Model with Logical Folders in &umbrello; 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 @@ -&UML; Basics +&UML; Basics -About &UML; -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. - -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 (OMG) and is the industry standard for graphically describing software. -&UML; is designed for Object Orientated software design and has limited use for other programming paradigms. -&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;: +About &UML; +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. + +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 (OMG) and is the industry standard for graphically describing software. +&UML; is designed for Object Orientated software design and has limited use for other programming paradigms. +&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;: -Use Case Diagrams show actors (people or other users of the system), use cases (the scenarios when they use the system), and their relationships - -Class Diagrams show classes and the relationships between them - -Sequence Diagrams show objects and a sequence of method calls they make to other objects. - -Collaboration Diagrams show objects and their relationship, putting emphasis on the objects that participate in the message exchange +Use Case Diagrams show actors (people or other users of the system), use cases (the scenarios when they use the system), and their relationships + +Class Diagrams show classes and the relationships between them + +Sequence Diagrams show objects and a sequence of method calls they make to other objects. + +Collaboration Diagrams show objects and their relationship, putting emphasis on the objects that participate in the message exchange -State Diagrams show states, state changes and events in an object or a part of the system - -Activity Diagrams show activities and the changes from one activity to another with the events occurring in some part of the system - -Component Diagrams show the high level programming components (such as KParts or Java Beans). - -Deployment Diagrams show the instances of the components and their relationships. +State Diagrams show states, state changes and events in an object or a part of the system + +Activity Diagrams show activities and the changes from one activity to another with the events occurring in some part of the system + +Component Diagrams show the high level programming components (such as KParts or Java Beans). + +Deployment Diagrams show the instances of the components and their relationships. - + - -&UML; Elements + +&UML; Elements -Use Case Diagram -Use Case Diagrams describe the relationships and dependencies between a group of Use Cases and the Actors participating in the process. -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, what the system should do but do not — and cannot — specify how this is to be achieved. +Use Case Diagram +Use Case Diagrams describe the relationships and dependencies between a group of Use Cases and the Actors participating in the process. +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, what the system should do but do not — and cannot — specify how this is to be achieved. -An example Use Case diagram. +An example Use Case diagram. - &umbrello; showing a Use Case Diagram + &umbrello; showing a Use Case Diagram - &umbrello; showing a Use Case Diagram + &umbrello; showing a Use Case Diagram -Use Case -A Use Case describes — from the point of view of the actors — a group of activities in a system that produces a concrete, tangible result. -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). -When working with Use Cases, it is important to remember some simple rules: - Each Use Case is related to at least one actor - Each Use Case has an initiator (&ie; an actor) - Each Use Case leads to a relevant result (a result with business value) +Use Case +A Use Case describes — from the point of view of the actors — a group of activities in a system that produces a concrete, tangible result. +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). +When working with Use Cases, it is important to remember some simple rules: + Each Use Case is related to at least one actor + Each Use Case has an initiator (&ie; an actor) + Each Use Case leads to a relevant result (a result with business value) -Use Cases can also have relationships with other Use Cases. The three most typical types of relationships between Use Cases are: +Use Cases can also have relationships with other Use Cases. The three most typical types of relationships between Use Cases are: -<<include>> which specifies that a Use Case takes place inside another Use Case -<<extends>> which specifies that in certain situations, or at some point (called an extension point) a Use Case will be extended by another. -Generalisation specifies that a Use Case inherits the characteristics of the Super-Use Case, and can override some of them or add new ones in a similar way as the inheritance between classes. +<<include>> which specifies that a Use Case takes place inside another Use Case +<<extends>> which specifies that in certain situations, or at some point (called an extension point) a Use Case will be extended by another. +Generalisation specifies that a Use Case inherits the characteristics of the Super-Use Case, and can override some of them or add new ones in a similar way as the inheritance between classes. -Actor -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. -Actors do not represent the physical people or systems, but their role. 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 Support Staff and an actor Sales Representative +Actor +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. +Actors do not represent the physical people or systems, but their role. 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 Support Staff and an actor Sales Representative -Use Case Description -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. +Use Case Description +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. - + -Class Diagram -Class Diagrams show the different classes that make up a system and how they relate to each other. Class Diagrams are said to be static diagrams because they show the classes, along with their methods and attributes as well as the static relationships between them: which classes know about which classes or which classes are part of another class, but do not show the method calls between them. +Class Diagram +Class Diagrams show the different classes that make up a system and how they relate to each other. Class Diagrams are said to be static diagrams because they show the classes, along with their methods and attributes as well as the static relationships between them: which classes know about which classes or which classes are part of another class, but do not show the method calls between them. -An example of a Class Diagram +An example of a Class Diagram - &umbrello; showing a Class Diagram + &umbrello; showing a Class Diagram - &umbrello; showing a Class Diagram + &umbrello; showing a Class Diagram -Class -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 Type 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. -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 compartments inside the rectangle. +Class +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 Type 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. +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 compartments inside the rectangle. -A Class in &UML; +A Class in &UML; - Visual representation of a Class in &UML; + Visual representation of a Class in &UML; - Visual representation of a Class in &UML; + Visual representation of a Class in &UML; -Attributes -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: +Attributes +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: -+ Stands for public attributes -# Stands for protected attributes -- Stands for private attributes ++ Stands for public attributes +# Stands for protected attributes +- Stands for private attributes -Operations -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: -+ Stands for public operations -# Stands for protected operations -- Stands for private operations +Operations +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: ++ Stands for public operations +# Stands for protected operations +- Stands for private operations -Templates -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. +Templates +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. -Class Associations -Classes can relate (be associated with) to each other in different ways: +Class Associations +Classes can relate (be associated with) to each other in different ways: -Generalisation -Inheritance is one of the fundamental concepts of Object Orientated programming, in which a class gains 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. -In &UML;, a Generalisation 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. -Generalisation +Generalisation +Inheritance is one of the fundamental concepts of Object Orientated programming, in which a class gains 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. +In &UML;, a Generalisation 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. +Generalisation - Visual representation of a generalisation in &UML; + Visual representation of a generalisation in &UML; - Visual representation of a generalisation in &UML; + Visual representation of a generalisation in &UML; @@ -380,35 +171,21 @@ -Associations -An association represents a relationship between classes, and gives the common semantics and structure for many types of connections between objects. -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 link. -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. -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 (*) on the maximum side representing infinite. -&UML; Association +Associations +An association represents a relationship between classes, and gives the common semantics and structure for many types of connections between objects. +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 link. +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. +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 (*) on the maximum side representing infinite. +&UML; Association - Visual representation of an Association in &UML; + Visual representation of an Association in &UML; - Visual representation of an Association in &UML; + Visual representation of an Association in &UML; @@ -416,367 +193,226 @@ -Aggregation -Aggregations are a special type of associations in which the two participating classes don't have an equal status, but make a whole-part 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. -In &UML;, Aggregations are represented by an association that shows a rhomb on the side of the whole. -Aggregation +Aggregation +Aggregations are a special type of associations in which the two participating classes don't have an equal status, but make a whole-part 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. +In &UML;, Aggregations are represented by an association that shows a rhomb on the side of the whole. +Aggregation - Visual representation of an Aggregation relationship in &UML; + Visual representation of an Aggregation relationship in &UML; - Visual representation of an Aggregation relationship in &UML; + Visual representation of an Aggregation relationship in &UML; -Composition -Compositions are associations that represent very strong 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. -In &UML;, Compositions are represented by a solid rhomb on the side of the whole. - -Composition +Composition +Compositions are associations that represent very strong 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. +In &UML;, Compositions are represented by a solid rhomb on the side of the whole. + +Composition - Visual representation of a Composition relationship in &UML; + Visual representation of a Composition relationship in &UML; - + - + -Other Class Diagram Items -Class diagrams can contain several other items besides classes. +Other Class Diagram Items +Class diagrams can contain several other items besides classes. -Interfaces -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. +Interfaces +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. -Datatypes -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. +Datatypes +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. -Enums -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. +Enums +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. -Packages -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. +Packages +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. - + -Sequence Diagrams +Sequence Diagrams -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. +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. -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. +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. -Sequence Diagram +Sequence Diagram - &umbrello; showing a Sequence Diagram + &umbrello; showing a Sequence Diagram - &umbrello; showing a Sequence Diagram + &umbrello; showing a Sequence Diagram -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. - +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. + -Collaboration Diagrams +Collaboration Diagrams -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. +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. -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. +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. -Collaboration +Collaboration - &umbrello; showing a Collaboration Diagram + &umbrello; showing a Collaboration Diagram - &umbrello; showing a Collaboration Diagram + &umbrello; showing a Collaboration Diagram - + -State Diagram -State Diagrams show the different states of an Object during its life and the stimuli that cause the Object to change its state. -State Diagrams exhibit Objects as state machines 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 NetServer can be in one of following states during its life: +State Diagram +State Diagrams show the different states of an Object during its life and the stimuli that cause the Object to change its state. +State Diagrams exhibit Objects as state machines 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 NetServer can be in one of following states during its life: -Ready -Listening -Working -Stopped +Ready +Listening +Working +Stopped -and the events that can cause the Object to change states are +and the events that can cause the Object to change states are -Object is created -Object receives message listen -A Client requests a connection over the network -A Client terminates a request -The request is executed and terminated -Object receives message stop -etc +Object is created +Object receives message listen +A Client requests a connection over the network +A Client terminates a request +The request is executed and terminated +Object receives message stop +etc -State Diagram +State Diagram - &umbrello; showing a State Diagram + &umbrello; showing a State Diagram - &umbrello; showing a State Diagram + &umbrello; showing a State Diagram -State -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. -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. -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. +State +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. +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. +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. - + -Activity Diagram -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. +Activity Diagram +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. -An example Activity Diagram. +An example Activity Diagram. - &umbrello; showing an Activity Diagram + &umbrello; showing an Activity Diagram - &umbrello; showing an Activity Diagram + &umbrello; showing an Activity Diagram -Activity Diagrams are similar to procedural Flux Diagrams, with the difference that all Activities are clearly attached to Objects. - -Activity Diagrams are always associated to a Class, an Operation or a Use Case. - -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) +Activity Diagrams are similar to procedural Flux Diagrams, with the difference that all Activities are clearly attached to Objects. + +Activity Diagrams are always associated to a Class, an Operation or a Use Case. + +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) -Activity -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. -Activities can form hierarchies, this means that an Activity can be composed of several detail Activities, in which case the incoming and outgoing transitions should match the incoming and outgoing transitions of the detail diagram. +Activity +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. +Activities can form hierarchies, this means that an Activity can be composed of several detail Activities, in which case the incoming and outgoing transitions should match the incoming and outgoing transitions of the detail diagram. - + -Helper Elements -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 +Helper Elements +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 -Text lines -Text Notes and anchors -Boxes - -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. - -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 belongs to a specific object or situation. - -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. +Text lines +Text Notes and anchors +Boxes + +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. + +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 belongs to a specific object or situation. + +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. - + -Component Diagrams -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. +Component Diagrams +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. -Components can have interfaces (&ie; abstract classes with operations) that allow associations between components. +Components can have interfaces (&ie; abstract classes with operations) that allow associations between components. -Deployment Diagrams +Deployment Diagrams -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). +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). - + 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 @@ -Working with &umbrello; +Working with &umbrello; -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 right clicking it will greatly speed up your work. +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 right clicking it will greatly speed up your work. -User Interface -&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. -These areas are called: +User Interface +&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. +These areas are called: -Tree View -Work Area -Documentation Window +Tree View +Work Area +Documentation Window -&umbrello;'s User Interface +&umbrello;'s User Interface - &umbrello;'s User Interface + &umbrello;'s User Interface - &umbrello;'s User Interface + &umbrello;'s User Interface -Tree View -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. -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) +Tree View +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. +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) -Documentation Window -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. +Documentation Window +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. -Work Area -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. +Work Area +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. - + -Creating, Loading and Saving Models -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. +Creating, Loading and Saving Models +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. -New Model -If at any time you need to create a new model you can do this by selecting the New entry from the File menu, or by clicking on the New 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. +New Model +If at any time you need to create a new model you can do this by selecting the New entry from the File menu, or by clicking on the New 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. -Save Model -You can save your model at any time by selecting the option Save from the File Menu or by clicking on the Save button from the application toolbar. If you need to save your model under a different name you can use the option Save As from the File Menu. -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 Settings from &umbrello; +Save Model +You can save your model at any time by selecting the option Save from the File Menu or by clicking on the Save button from the application toolbar. If you need to save your model under a different name you can use the option Save As from the File Menu. +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 Settings from &umbrello; -Load Model -For loading an already existing model you may select the option Open from the File Menu or click on the Open icon from the application toolbar. The most recently used models are also available under the submenu Open Recent in the File Menu to speed up access to your most frequently used models. -&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. +Load Model +For loading an already existing model you may select the option Open from the File Menu or click on the Open icon from the application toolbar. The most recently used models are also available under the submenu Open Recent in the File Menu to speed up access to your most frequently used models. +&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. - + -Editing Models -In &umbrello;, there are basically two ways for editing the elements in your model. -Edit model elements directly through the Tree View -Edit model elements through a Diagram +Editing Models +In &umbrello;, there are basically two ways for editing the elements in your model. +Edit model elements directly through the Tree View +Edit model elements through a Diagram -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. Right 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 Use Case View or a Logical View, Actors, Use Cases, Classes, etc. -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 Properties from the context menu shown when right clicking on the items in the Tree View. -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. +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. Right 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 Use Case View or a Logical View, Actors, Use Cases, Classes, etc. +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 Properties from the context menu shown when right clicking on the items in the Tree View. +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. -Adding and Removing Diagrams -Your &UML; model consists of a set of &UML; elements and associations between them. However you cannot see the model directly, you use Diagrams to look at it. +Adding and Removing Diagrams +Your &UML; model consists of a set of &UML; elements and associations between them. However you cannot see the model directly, you use Diagrams to look at it. -Creating Diagrams -To create a new diagram in your model simply select the diagram type you need from the New submenu in the Diagram 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. -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 New 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. +Creating Diagrams +To create a new diagram in your model simply select the diagram type you need from the New submenu in the Diagram 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. +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 New 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. -Removing Diagrams -Should you need to remove a diagram from your model, you can do this by making it active and selecting Delete from the Diagram Menu. You can also achieve this by selecting Delete from the diagrams context menu in the Tree View -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. +Removing Diagrams +Should you need to remove a diagram from your model, you can do this by making it active and selecting Delete from the Diagram Menu. You can also achieve this by selecting Delete from the diagrams context menu in the Tree View +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. -Renaming Diagrams -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. -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. +Renaming Diagrams +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. +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. -Editing Diagrams -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. -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 model. As you already know, Diagrams are views 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. +Editing Diagrams +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. +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 model. As you already know, Diagrams are views 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. -Insert Elements -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: +Insert Elements +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: -Dragging existing elements in your model from the Tree View -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 +Dragging existing elements in your model from the Tree View +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 -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 -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). -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. -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 Unique Name. So that if you have a class in one diagram whose name is ClassA and then you use the insert Class tool to insert a class into another diagram you cannot name this new class ClassA 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 same 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. +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 +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). +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. +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 Unique Name. So that if you have a class in one diagram whose name is ClassA and then you use the insert Class tool to insert a class into another diagram you cannot name this new class ClassA 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 same 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. -Deleting Elements -You can delete any element by selecting the option Delete from its context menu. -Again, there is a big 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 model. Since the element no longer exist in your model, it will be automatically removed from all the diagrams it appears in. +Deleting Elements +You can delete any element by selecting the option Delete from its context menu. +Again, there is a big 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 model. Since the element no longer exist in your model, it will be automatically removed from all the diagrams it appears in. -Editing Elements -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 Properties 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. +Editing Elements +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 Properties 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. -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. +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. -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. +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. -Editing Classes -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. -In the properties dialogue for a class you can set everything, from the colour it uses to the operations and attributes it has. +Editing Classes +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. +In the properties dialogue for a class you can set everything, from the colour it uses to the operations and attributes it has. -Class General Settings -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. +Class General Settings +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. -Class Attribute Settings -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. +Class Attribute Settings +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. -Class Operations Settings -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 Operation Properties dialogue. If you want to add parameters to your operation you need to click the New Parameter button, which will show the Parameter Properties dialogue. This page is always available +Class Operations Settings +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 Operation Properties dialogue. If you want to add parameters to your operation you need to click the New Parameter button, which will show the Parameter Properties dialogue. This page is always available -Class Template Settings -This page allows you to add class templates which are unspecified classes or datatypes. In Java 1.5 these will be called Generics. +Class Template Settings +This page allows you to add class templates which are unspecified classes or datatypes. In Java 1.5 these will be called Generics. -Class Associations Page -The Class Associations 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. -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. +Class Associations Page +The Class Associations 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. +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. -Class Display Page -In the Display Options 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 -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 display options for the diagram. This means that hiding 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 +Class Display Page +In the Display Options 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 +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 display options for the diagram. This means that hiding 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 -Class Colour Page -In the Widget Colour 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. +Class Colour Page +In the Widget Colour 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. -Associations -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. -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 not a drag from one object to the other. -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 -Right 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 Delete option from this context menu. You can also select the Properties option and, depending on the association type edit attributes such as roles and multiplicity. +Associations +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. +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 not a drag from one object to the other. +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 +Right 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 Delete option from this context menu. You can also select the Properties option and, depending on the association type edit attributes such as roles and multiplicity. -Anchor Points -Associations are drawn, by default, as a straight line connecting the two objects in the diagram. -You can add anchor points to bend an association by double 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 -If you need to remove an anchor point, double click on it again to remove it -Note that the only way to edit the properties of an association is through the context menu. If you try to double click on it as with other &UML; objects, this will only insert an anchor point. +Anchor Points +Associations are drawn, by default, as a straight line connecting the two objects in the diagram. +You can add anchor points to bend an association by double 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 +If you need to remove an anchor point, double click on it again to remove it +Note that the only way to edit the properties of an association is through the context menu. If you try to double click on it as with other &UML; objects, this will only insert an anchor point. -Notes, Text and Boxes -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. -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 double clicking on them as well. +Notes, Text and Boxes +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. +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 double clicking on them as well. -Anchors -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 belongs to that particular element. -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. +Anchors +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 belongs to that particular element. +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. -- cgit v1.2.1