Minor documentation updates

diff --git a/misc/translator/Makefile b/misc/translator/Makefile
new file mode 100644 (file)
index 0000000..9706c70
--- /dev/null
+++ b/misc/translator/Makefile
@@ -0,0 +1,4 @@
+all: translator_doc.txt
+
+%.txt: %.html
+       LANG=C w3m $< > $@

diff --git a/misc/translator/translator_doc.html b/misc/translator/translator_doc.html
new file mode 100644 (file)
index 0000000..abf235b
--- /dev/null
+++ b/misc/translator/translator_doc.html
@@ -0,0 +1,76 @@
+<h1>TRANSLATION TOOL, V3.0:
+<br>======================</h1>
+
+<p>
+This transation tool should greatly help Koha translators.
+It's composed of 2&nbsp;scripts:
+
+<ul>
+<li>xgettext.pl, that extracts the texts in a template,
+    and which is called by the script
+<li>tmpl_process3.tmpl, which can do 3 things:
+    <ul>
+    <li>create a file with all the "translatable strings" in all files in a directory (& its subdirectories)
+    <li>update an existing translation file.
+    <li>rebuild translated templates from english & translation file.
+    </ul>
+</ul>
+<p>
+Call tmpl_process3.pl --help to get a more detailed explanation.
+Some additional explanations are also available by calling
+perldoc tmpl_process3.pl.
+
+<h2>HOW TO TRANSLATE Koha:
+<br>=====================</h2>
+
+<ol>
+<li>Create your translation file:
+    <blockquote>
+./tmpl_process.pl create -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -s css_opac_fr_FR.po -r
+    </blockquote>
+    <p>(In the above example,
+    /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/
+    contains the English templates in the "default" theme,
+    and po/css_opac_fr_FR.po is where you want the generated PO file to appear.)
+<li>Translate your css_opac_fr_FR.po file
+    using a text editor or a PO file translation tool.
+<li>Create your translated templates:
+    <blockquote>
+./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/ -s css_opac_fr_FR.po -r
+    </blockquote>
+    <p>
+    (In the above example,
+    /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/
+    is where you want your translated templates to be saved.)
+<li>Copy images/css files in your new directory (as they are NOT moved by tmpl_process3.pl install).
+</ol>
+
+<p>
+If something changes in English version:
+<ol>
+<li>Update your translation file:
+    <blockquote>
+./tmpl_process.pl update -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -s po/css_opac_fr_FR.po -r
+    </blockquote>
+<li>Translate your new css_opac_fr_FR.po file.
+    Look for strings marked as "fuzzy" and strings that are not translated.
+<li>Create your translated templates:
+    <blockquote>
+./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/ -s po/css_opac_fr_FR.po -r
+    </blockquote>
+<li>Copy new images/css files in your new directory if needed
+</ol>
+
+<h2>WEAKNESSES
+<br>==========</h2>
+<p>For a somewhat up-to-date list of weaknesses,
+please run <code>perldoc xgettext.pl</code>
+and <code>perldoc tmpl_process3.pl</code>
+and read the BUGS sections.
+
+<h2>COPYRIGHT
+<br>=========</h2>
+<ul>
+<li>Paul Poulain (paul.poulain _@_ free.fr) & Jerome Vizcaino (vizcainj _@_ esiee.fr)
+<li>Parts of V3.0 by Ambrose Li (acli _@_ ada.dhs.org)
+</ul>

diff --git a/misc/translator/translator_doc.txt b/misc/translator/translator_doc.txt
index 4489c94..7baecfb 100644 (file)
--- a/misc/translator/translator_doc.txt
+++ b/misc/translator/translator_doc.txt
@@ -1,75 +1,71 @@
-TRANSLATION TOOL , V2.0:
-============
-This transation tool should greatly help Koha translators.
-It's composed of 2 script :
-* test-extract.pl, that extracts the texts in a template. It is called by
-* tmpl_process.
-tmpl process can do 3 things :
-- create a file with all sentences all files in a directory (& it's subdirectories)
-- update an existing translation file.
-- rebuild translated templates from english & translation file.
+TRANSLATION TOOL, V3.0:
+======================
 
-Call tmpl_process --help to get full explanations.
+This transation tool should greatly help Koha translators. It's composed of
+2 scripts:
 
-HOW TO TRANSLATE Koha :
-============
-1- create your translation file :
-./tmpl_process.pl create -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -s opac.fr -r
-2- translate your opac.fr file (english & other_language being separated by a tab, using IGNORE and LIMITED pragmas, see below)
-3- create your translated version :
-./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/ -s opac.fr -r
-4- copy images/css files in your new directory (as they are NOT moved by tmpl_process.pl install)
+  * xgettext.pl, that extracts the texts in a template, and which is called by
+    the script
+  * tmpl_process3.tmpl, which can do 3 things:
+      + create a file with all the "translatable strings" in all files in a
+        directory (& its subdirectories)
+      + update an existing translation file.
+      + rebuild translated templates from english & translation file.
 
-If something changes in english version :
-1- update your translation file :
-./tmpl_process.pl update -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -s opac.fr -r
-2- translate new  your opac.fr file (english & other_language being separated by a tab, using IGNORE and LIMITED pragmas, see below)
-3- create your translated version :
-./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/ -s opac.fr -r
-4- copy new images/css files in your new directory if needed
+Call tmpl_process3.pl --help to get a more detailed explanation. Some
+additional explanations are also available by calling perldoc tmpl_process3.pl.
 
-WEAKNESSES
-=======
-I've found some weaknesses (some solvable probably, but maybe some unsolvable)
-- HTML::Templates pb :
- if there is only a <TMPL* > tag between 2 strings, text-extract sometimes merges both strings, and so can't replace them in the translated template. I've solved all those cases with a <br/> or another HTML statement.
-  The text-extract2.pl filter attempts to address this problem; it seems that the new filter is now working correctly.
+HOW TO TRANSLATE Koha:
+=====================
+
+ 1. Create your translation file:
+   
+        ./tmpl_process.pl create -i /home/paul/koha.dev/koha/koha-tmpl/
+        opac-tmpl/default/en/ -s css_opac_fr_FR.po -r
+   
+    (In the above example, /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default
+    /en/ contains the English templates in the "default" theme, and po/
+    css_opac_fr_FR.po is where you want the generated PO file to appear.)
+ 2. Translate your css_opac_fr_FR.po file using a text editor or a PO file
+    translation tool.
+ 3. Create your translated templates:
+   
+        ./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/
+        opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/
+        default/fr2/ -s css_opac_fr_FR.po -r
+   
+    (In the above example, /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default
+    /fr2/ is where you want your translated templates to be saved.)
+ 4. Copy images/css files in your new directory (as they are NOT moved by
+    tmpl_process3.pl install).
 
-- SHORT STATEMENTS
- short statements (like "in") can be replaced stupidly (like in cgi-bin => gives cgi-bdans in french). the workaround has been to replace only complete words (
-line 185 of tmpl_process :
-$line =~ s/(\W)$text(\W)/$1$subst$2/g;
-)
-Don't seem to have any side effect.
+If something changes in English version:
 
-- WORD exist in FILENAME
-words that are in the templates and in a perl script name are replaced !
-For example : Search is replace by Recherche in french, thus,giving <a href="cgi-bin/opac-Recherche.pl">, which is wrong...
-2 ways to solve this problem, IGNORE & LIMITED pragma.
-IGNORE :
-if a line in translation file is :
-this_original_string   IGNORE
-it is ignored during translation.
-LIMITED :
-if a line in translation file is :
-this_original_string LIMITED;the_translation_string
-The string is translated only if :
-* has a > just before
-* has <space>title=" just before
-* has <space>alt=" just before.
-This prevent stupid replaces, at the cost of some missing translation maybe.
+ 1. Update your translation file:
+   
+        ./tmpl_process.pl update -i /home/paul/koha.dev/koha/koha-tmpl/
+        opac-tmpl/default/en/ -s po/css_opac_fr_FR.po -r
+   
+ 2. Translate your new css_opac_fr_FR.po file. Look for strings marked as
+    "fuzzy" and strings that are not translated.
+ 3. Create your translated templates:
+   
+        ./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/
+        opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/
+        default/fr2/ -s po/css_opac_fr_FR.po -r
+   
+ 4. Copy new images/css files in your new directory if needed
 
-- MISSING STRINGS
-Maybe some strings that should be translated are missing.
-You can add whatever you want in text-extract.pl.
-For instance, it extracts :
-- standard text
-- text in alt="SOMETEXT"
-- meta html encoding (8859-1) to enable non european translations.
+WEAKNESSES
+==========
 
-- DIFFERENT WORD ORDER
-Some languages have different word order than English in sentences, or even in dates. For these languages, it is impossible to make a good translation at the moment.
+For a somewhat up-to-date list of weaknesses, please run perldoc xgettext.pl
+and perldoc tmpl_process3.pl and read the BUGS sections.
 
 COPYRIGHT
-======
-@ paul poulain (paul.poulain _@_ free.fr) & Jerome Vizcaino vizcainj _@_ esiee.fr
+=========
+
+  * Paul Poulain (paul.poulain _@_ free.fr) & Jerome Vizcaino (vizcainj _@_
+    esiee.fr)
+  * Parts of V3.0 by Ambrose Li (acli _@_ ada.dhs.org)
+

diff --git a/misc/translator/xgettext.pl b/misc/translator/xgettext.pl
index 34a02c0..a3d65ed 100755 (executable)
--- a/misc/translator/xgettext.pl
+++ b/misc/translator/xgettext.pl
@@ -406,8 +406,9 @@ the gettext format.
 
 =back
 
-Note that this script is experimental and should still be
-considered unstable.
+This script has already been in use for over a year and should
+be reasonable stable. Nevertheless, it is still somewhat
+experimental and there are still some issues.
 
 Please refer to the explanation in tmpl_process3 for further
 details.
@@ -439,7 +440,7 @@ A suitable definition of such a function can be
 
 =head1 SEE ALSO
 
-tmpl_process.pl,
+tmpl_process3.pl,
 xgettext(1),
 Locale::PO(3),
 translator_doc.txt
@@ -460,4 +461,8 @@ xgettext(1)'s sort option. This will result in translation
 strings inside the generated PO file spuriously moving about
 when tmpl_process3.pl calls msgmerge(1) to update the PO file.
 
+It sometimes generates strings with spurious leading spaces,
+leading to failure to match the strings when actually generating
+translated files.  The cause of this is not yet known.
+
 =cut