Version: 1.3.1 (using KDE KDE 3.2.3) Installed from: Compiled From Sources Compiler: gcc-3.4.0 OS: Linux The section "6. Preferences"/"KBabel preferences"/"Sourcecode" is missing in the manual. (Every other part of the preference dialog is described in the manual.)
The manual is rather outdated :(
I will try to add an appendix to the KBabel documentation about source referencing. See also bug #86713 which de-facto tracks what is happening on this domain in KBabel's source code. Have a nice day!
SVN commit 492145 by goutte: Do most of the documentation of the source reference part of the project settings (To finish it, however, I would need to be able to write what I want to tell.) CCBUG:85885 M +105 -1 preferences.docbook --- branches/KDE/3.5/kdesdk/doc/kbabel/preferences.docbook #492144:492145 @@ -979,8 +979,112 @@ </mediaobject> </screenshot> -<para><remark>TODO</remark></para> +<para> +This dialog is for setting how KBabel should create the full path of each source references, +which are in the comments of each entry of a <acronym>PO</acronym> file. +</para> +<sect3> +<title>Dialog elements</title> + +<para> +In the text edit <guilabel>Base folder for source code</guilabel>, you can set a +base folder where the source code of your project is. This defines the variable +<userinput>@CODEROOT@</userinput>, which is described below. +</para> + +<para> +In the group <guilabel>Path Patterns</guilabel>, you can define patterns or rules +to construct the paths out of a few path elements with the help of a few variables: +<userinput>@CODEROOT@</userinput>, <userinput>@PACKAGEDIR@</userinput>, +<userinput>@PACKAGE@</userinput>, <userinput>@COMMENTPATH@</userinput>, +<userinput>@POFILEDIR@</userinput>, which are defined below. +</para> + +<note><para> +The variable @PODIRFILE@ was introduced in &kbabel; version 1.11.1 (for &kde; 3.5.1). +</para></note> + +<para> +With the button <guibutton>Add</guibutton>, you can add the line from the text box +to the list of used path patterns. With the button <guibutton>Remove</guibutton>, +you can remove the selected pattern from the list. With the buttons +<guibutton>Up</guibutton> and <guibutton>Down</guibutton>, you can change the priority of +the path patterns. +</para> + +</sect3> + +<sect3> +<title>The variables</title> + +<itemizedlist> +<listitem><para> +<userinput>@CODEROOT@</userinput>: The base folder of the source code. +</para></listitem> +<listitem><para> +<userinput>@PACKAGEDIR@</userinput>: The folder of the package (i.e. <acronym>PO</acronym> file). +</para></listitem> +<listitem><para> +<userinput>@PACKAGE@</userinput>: The package name (i.e. <acronym>PO</acronym> file name without extension). +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>: The folder of the <acronym>PO</acronym> file. +</para></listitem> +<listitem><para> +<userinput>@COMMENTPATH@</userinput>: The relative path given as source reference in the comment of an entry of the <acronym>PO</acronym> file. +</para></listitem> +</itemizedlist> + +<important><para> +The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> have similar +meaning but not the same result. The variable <userinput>@POFILEDIR@</userinput> will work for every file, +<userinput>@PACKAGEDIR@</userinput> might not. +<remark>TODO: that is badly explained!</remark> +</para></important> + +<note><para> +The variables <userinput>@CODEROOT@</userinput> and <userinput>@POFILEDIR@</userinput> can only be used at +the beginning of a pattern to be useful. The variable <userinput>@COMMENTPATH@</userinput> can only be used at the +end of a pattern. The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> +should not be used in the same pattern. The variables <userinput>@CODEROOT@</userinput> and <userinput>@POFILEDIR@</userinput> should not be used in the same pattern either. +</para></note> + +</sect3> + +<sect3> +<title>The default path patterns</title> + +<para> +From &kbabel; 1.11.1 (of &kde; 3.5.1) on, there are five default path patterns: +</para> + +<itemizedlist> +<listitem><para> +<userinput>@PACKAGEDIR@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGEDIR@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>/../<userinput>@COMMENTPATH@</userinput> +</para></listitem> +</itemizedlist> + +<note><para> +&kde; projects need one of the three first patterns. +The last pattern is typical for &GNU; projects, where the source references are compared to +the parent of the directory where the PO file is. +</para></note> + +</sect3> + </sect2> <sect2 id="preferences-project-miscellaneous">
SVN commit 492232 by goutte: - Try to give some hints to create path patterns for the source reference (The difference between @POFILEDIR@ and @PACKAGEDIR@ would still remain, but it is not part of the bug report anyway.) BUG:85885 - Add id attributes to the 2 wizard pages' description. M +52 -9 preferences.docbook --- branches/KDE/3.5/kdesdk/doc/kbabel/preferences.docbook #492231:492232 @@ -497,7 +497,7 @@ <sect1 id="preferences-project-wizard"> <title>New Project Wizard</title> -<sect2> +<sect2 id="preferences-project-wizard-basic"> <title>Page 1</title> <screenshot> @@ -543,7 +543,7 @@ </sect2> -<sect2> +<sect2 id="preferences-project-wizard-catman"> <title>Page 2</title> <screenshot> @@ -552,7 +552,7 @@ <imageobject> <imagedata fileref="pref_wizard_page2.png" format="PNG"/> </imageobject> -<textobject><phrase>Project Wizard Page 1</phrase></textobject> +<textobject><phrase>Project Wizard Page 2</phrase></textobject> </mediaobject> </screenshot> @@ -980,7 +980,7 @@ </screenshot> <para> -This dialog is for setting how KBabel should create the full path of each source references, +This dialog is for setting how KBabel should construct the full path from each source references, which are in the comments of each entry of a <acronym>PO</acronym> file. </para> @@ -989,20 +989,20 @@ <para> In the text edit <guilabel>Base folder for source code</guilabel>, you can set a -base folder where the source code of your project is. This defines the variable +base folder where the source code of your project is. This defines the value of the variable <userinput>@CODEROOT@</userinput>, which is described below. </para> <para> In the group <guilabel>Path Patterns</guilabel>, you can define patterns or rules -to construct the paths out of a few path elements with the help of a few variables: +to construct the paths with the help of a few variables: <userinput>@CODEROOT@</userinput>, <userinput>@PACKAGEDIR@</userinput>, <userinput>@PACKAGE@</userinput>, <userinput>@COMMENTPATH@</userinput>, <userinput>@POFILEDIR@</userinput>, which are defined below. </para> <note><para> -The variable @PODIRFILE@ was introduced in &kbabel; version 1.11.1 (for &kde; 3.5.1). +The variable <userinput>@PODIRFILE@</userinput> was introduced in &kbabel; version 1.11.1 (for &kde; 3.5.1). </para></note> <para> @@ -1046,7 +1046,8 @@ <note><para> The variables <userinput>@CODEROOT@</userinput> and <userinput>@POFILEDIR@</userinput> can only be used at the beginning of a pattern to be useful. The variable <userinput>@COMMENTPATH@</userinput> can only be used at the -end of a pattern. The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> +end of a pattern and is nearly mandatory. +The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> should not be used in the same pattern. The variables <userinput>@CODEROOT@</userinput> and <userinput>@POFILEDIR@</userinput> should not be used in the same pattern either. </para></note> @@ -1079,12 +1080,54 @@ <note><para> &kde; projects need one of the three first patterns. -The last pattern is typical for &GNU; projects, where the source references are compared to +The last pattern is typical for &GNU; projects, where the source references are related to the parent of the directory where the PO file is. </para></note> </sect3> +<sect3> +<title>Creating New Path Patterns</title> + +<para> +Even if normally the default path patterns should be enough, whatever +the project is a &GNU; one (or structured like a &GNU; project) or +if the project is for KDE. +</para> + +<note><para> +For &kde;, some <acronym>PO</acronym> files do not contain enough information +(including the file path and name) for &kbabel; to find the right source file +that is supposed to be refered. To fix that you would need precise path patterns +for such files, which is nearly impossible to define by the numbers of such files +in &kde;. But if you work often with such a file, may be it is worth to set +a path pattern explicitely for supporting that <acronym>PO</acronym> file. +</para></note> + +<para> +For creating your own path patterns, you can use the variables defined above, +but apart <userinput>@COMMENTPATH@</userinput> not any variable is mandatory to use. +(To be exact, <userinput>@COMMENTPATH@</userinput> is not mandatory either, +but not using it will probably lead to no result.) +</para> + +<para> +An example of path pattern could be that you want to display the source reference +of &kde;'s file desktop_kdebase.po. In that case you will probably need a path pattern like: +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGEDIR@</userinput>/kdebase/<userinput>@COMMENTPATH@</userinput> +(compared to one of the default path patterns, the sequence <userinput>@PACKAGE@</userinput> has been +replaced by kdebase). +</para> + +<para> +In case of really complex problems you can, of course, define an absolute path +without any variables beside <userinput>@COMMENTPATH@</userinput>, like for example: +/home/usr/kde-source/kdebase/<userinput>@COMMENTPATH@</userinput> assuming that +/home/usr/kde-source/kdebase is the path where the kdebase source module is. +</para> + +</sect3> + </sect2> <sect2 id="preferences-project-miscellaneous">
SVN commit 492260 by goutte: I have now looked closer at the problem and I think I know the difference between @PACKAGEDIR@ and @POFILEDIR@ for path patterns for source references (The main difference is due to the Catalog Manager) CCBUG:85885 M +2 -2 index.docbook M +11 -8 preferences.docbook --- branches/KDE/3.5/kdesdk/doc/kbabel/index.docbook #492259:492260 @@ -35,8 +35,8 @@ </authorgroup> -<date>2005-12-28</date> -<releaseinfo>3.5.1.02</releaseinfo> +<date>2005-12-29</date> +<releaseinfo>3.5.1.03</releaseinfo> <abstract> <para> --- branches/KDE/3.5/kdesdk/doc/kbabel/preferences.docbook #492259:492260 @@ -988,7 +988,7 @@ <title>Dialog elements</title> <para> -In the text edit <guilabel>Base folder for source code</guilabel>, you can set a +In the edit line <guilabel>Base folder for source code</guilabel>, you can set a base folder where the source code of your project is. This defines the value of the variable <userinput>@CODEROOT@</userinput>, which is described below. </para> @@ -1038,9 +1038,12 @@ <important><para> The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> have similar -meaning but not the same result. The variable <userinput>@POFILEDIR@</userinput> will work for every file, -<userinput>@PACKAGEDIR@</userinput> might not. -<remark>TODO: that is badly explained!</remark> +meaning but not the same result. The variable <userinput>@POFILEDIR@</userinput> +will always hold the folder of <acronym>PO</acronym> file, +<userinput>@PACKAGEDIR@</userinput> might not. If the <acronym>PO</acronym> file was loaded +by the help of the &catalogmanager; then <userinput>@PACKAGEDIR@</userinput> has only the part of +the path, based on the <acronym>PO</acronym> base path defined for the &catalogmanager; +<link linkend="preferences-project-folders">(see below)</link>. </para></important> <note><para> @@ -1079,7 +1082,7 @@ </itemizedlist> <note><para> -&kde; projects need one of the three first patterns. +&kde; projects need typically the third pattern. The last pattern is typical for &GNU; projects, where the source references are related to the parent of the directory where the PO file is. </para></note> @@ -1090,9 +1093,9 @@ <title>Creating New Path Patterns</title> <para> -Even if normally the default path patterns should be enough, whatever -the project is a &GNU; one (or structured like a &GNU; project) or -if the project is for KDE. +In most cases the default path patterns should be enough, whatever +the project is for KDE (assuming that you have set the correct base directory) +or if the project is a &GNU; one (or structured like a &GNU; project). </para> <note><para>