[kde-doc-english] [Bug 85885] kbabel: missing section in documentation for "6. Preferences"/"KBabel preferences"/"Sourcecode"

[Nicolas Goutte]

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
         
http://bugs.kde.org/show_bug.cgi?id=85885         




------- Additional Comments From nicolasg snafu de  2005-12-28 23:24 -------
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">