[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         
nicolasg snafu de changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |FIXED



------- Additional Comments From nicolasg snafu de  2005-12-29 11:35 -------
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">