trans-coord/gnun/server/gnun ChangeLog gnun.texi

[Yavor Doganov]

CVSROOT:        /cvsroot/trans-coord
Module name:    trans-coord
Changes by:     Yavor Doganov <yavor>   08/02/23 16:57:48

Modified files:
        gnun/server/gnun: ChangeLog gnun.texi 

Log message:
        (Concepts): Minor clarification.
        (New Translation): Use `free-sw' as an example to workaround TeX
        warnings.
        (Notes Slot, Credits Slot): New nodes.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/ChangeLog?cvsroot=trans-coord&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/gnun.texi?cvsroot=trans-coord&r1=1.3&r2=1.4

Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/trans-coord/trans-coord/gnun/server/gnun/ChangeLog,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- ChangeLog   21 Feb 2008 20:20:31 -0000      1.4
+++ ChangeLog   23 Feb 2008 16:57:48 -0000      1.5
@@ -1,3 +1,10 @@
+2008-02-23  Yavor Doganov  <address@hidden>
+
+       * gnun.texi (Concepts): Minor clarification.
+       (New Translation): Use `free-sw' as an example to workaround TeX
+       warnings.
+       (Notes Slot, Credits Slot): New nodes.
+
 2008-02-21  Yavor Doganov  <address@hidden>
 
        * gnun.mk (philosophy): Add `why-free'.

Index: gnun.texi
===================================================================
RCS file: /cvsroot/trans-coord/trans-coord/gnun/server/gnun/gnun.texi,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- gnun.texi   21 Feb 2008 20:18:04 -0000      1.3
+++ gnun.texi   23 Feb 2008 16:57:48 -0000      1.4
@@ -4,7 +4,7 @@
 @settitle GNUnited Nations Manual
 @c FIXME: Would be nice to have it in the format `%:b %:d, %:y', but
 @c in English.
address@hidden lastupdate 21.02.2008
address@hidden lastupdate 23.02.2008
 @afourpaper
 @c %**end of header
 
@@ -136,15 +136,16 @@
 @section What @acronym{GNU}nited Nations is and Should be
 
 The basic concept behind @acronym{GNUN} is that localization of HTML
-articles is similar to localization of computer programs.  In
-articles, like in programs, not every string is considered
-translatable, so translatable strings must be identified first, and
-then collected in a file (called ``PO template'') for translation.
-Articles, like programs, tend to change in time, but not every change
-in the sources calls for a translation update.  Sometimes the change
-does not affect the translatable strings, but sometimes it does.  So,
-translators must have means to identify those changes and apply the
-appropriate updates to the translation.
+articles is similar to localization of computer programs (or more
+precisely, of software documentation).  In articles, like in programs,
+not every string is considered translatable, so translatable strings
+must be identified first, and then collected in a file (called ``PO
+template'') for translation.  Articles, like programs, tend to change
+in time, but not every change in the sources calls for a translation
+update.  Sometimes the change does not affect the translatable
+strings, but sometimes it does.  So, translators must have means to
+identify those changes and apply the appropriate updates to the
+translation.
 
 The @acronym{GNU} @code{gettext} package already provides the needed
 infrastructure for maintaining translations using PO files.
@@ -650,17 +651,17 @@
 @node New Translation
 @subsection Starting a New Translation
 
-To start a new translation, the easiest way is to copy the existing POT
-as @address@hidden, where @var{lang} is your language code.
-For example, to prepare for a new translation of the essay
address@hidden://www.gnu.org/philosophy/freedom-or-copyright.html}, you can
-simply do @command{cd philosophy/po ; cp freedom-or-copyright.pot
address@hidden and then edit the latter.  If
address@hidden does not exist it is because either the
-article is not yet ``templated'' (i.e. migrated to the new style), or
-the @acronym{GNUN} maintainers have not yet added it to the value of the
-appropriate variable in @file{server/gnun/gnun.mk}.  In that case, just
-ask them to do the necessary in order the POT to be generated.
+To start a new translation, the easiest way is to copy the existing
+POT as @address@hidden, where @var{lang} is your language
+code.  For example, to prepare for a new translation of the essay
address@hidden://www.gnu.org/philosophy/free-sw.html}, you can simply do
address@hidden philosophy/po ; cp free-sw.pot address@hidden and
+then edit the latter.  If @file{free-sw.pot} does not exist it is
+because either the article is not yet ``templated'' (i.e. migrated to
+the new style), or the @acronym{GNUN} maintainers have not yet added
+it to the value of the appropriate variable in
address@hidden/gnun/gnun.mk}.  In that case, just ask them to do the
+necessary in order the POT to be generated.
 
 You could also use the @command{msginit} utility that would populate
 the PO file header with the right information, provided your
@@ -696,14 +697,14 @@
 
 @example
 @group
-# Bulgarian translation of 
http://www.gnu.org/philosophy/@/freedom-or-copyright.html
+# Bulgarian translation of http://www.gnu.org/philosophy/@/free-sw.html
 # Copyright (C) 2008 Free Software Foundation, Inc.
 # This file is distributed under the same license as the gnu.org article.
 # Yavor Doganov <yavor@@gnu.org>, 2008.
 #
 msgid ""
 msgstr ""
-"Project-Id-Version: freedom-or-copyright.html\n"
+"Project-Id-Version: free-sw.html\n"
 "POT-Creation-Date: 2008-02-06 16:25-0500\n"
 "PO-Revision-Date: 2008-02-09 15:23+0200\n"
 "Last-Translator: Yavor Doganov <yavor@@gnu.org>\n"
@@ -730,22 +731,14 @@
 @table @samp
 @item *GNUN-SLOT: TRANSLATOR'S NOTES*
 This is for translator's notes that are injected in the resulting
-translation.  See FIXME:Foo, for more information.  If your
+translation.  @xref{Notes Slot}, for more information.  If your
 translation does not have notes, you @emph{must} translate this as a
 space, that is, @key{SPC}.
 
 @item *GNUN-SLOT: TRANSLATOR'S CREDITS*
 This is again optional, and should contain the name (and address) of
-the person who made the translation.  For example:
-
address@hidden
-<b>Traduction</b>: Benjamin Drieu <a
-href="mailto:foo@@example.org";>&lt;foo@@example.org&gt;</a>, 2007,
-2008.
address@hidden example
-
-``Translate'' this string as a space (@key{SPC}) if you do not want
-your name to appear there.
+the person who made the translation.  ``Translate'' this string as a
+space (@key{SPC}) if you do not want your name to appear there.
 @end table
 
 Most of the PO editors do not wrap long lines that inevitably appear
@@ -766,6 +759,91 @@
 update of all translations.  Such things happen to everyone, so it is
 a good practice to check before you actually commit.
 
address@hidden
+* Notes Slot::          How to handle translator's notes.
+* Credits Slot::        Translator's credits.
address@hidden menu
+
address@hidden Notes Slot
address@hidden The Special Slot for Translator's Notes
+
+Sometimes it is necessary to complement the translation of an essay
+with translator's notes.  The special message @code{*GNUN-SLOT:
+TRANSLATOR'S NOTES*} is designed to serve this purpose.  If your
+translation doesn't have notes, you should ``translate'' the
address@hidden as a space (@key{SPC})---otherwise the text of the
address@hidden will appear in the HTML translation, which is not what
+you want.  Here is an example how to use translators' notes in a PO
+file:
+
address@hidden
address@hidden
+# type: Content of: <p>
+#: ../../philosophy/po/free-sw.proto:22
+msgid ""
+"To understand the concept, you should think of <q>free</q> "
+"as in <q>free speech,</q> not as in <q>free beer.</q>"
+msgstr ""
+"Translated message, where you want to clarify beer<sup><a "
+"href=\"#TransNote1\">1</a></sup>, presumably because the "
+"expression in your language is different"
address@hidden
address@hidden
+# type: Content of: <div>
+#. TRANSLATORS: Use space (SPC) as msgstr if you don't have notes.
+#: ../../philosophy/po/free-sw.proto:274
+msgid "*GNUN-SLOT: TRANSLATOR'S NOTES*"
+msgstr ""
+"<b>Translator's notes</b>:\n"
+"<ol>\n"
+"<li id=\"TransNote1\">Note clarifying the text.</li>\n"
+"</ol>\n"
address@hidden group
address@hidden example
+
+Certainly, everything in the @code{msgstr}s should be in your native
+language; we use English here in order the example to be understood by
+everyone.  If you have more notes, each subsequent one should be with
+incremented number, i.e. `TransNote2', `TransNote2', etc. and you have
+to add them as more @code{<li>} elements accordingly.
+
+Do not worry about the @code{\n} character---it is inserted
+automatically when you press @key{RET}.  It is not compulsory that
+notes start on a new line, this is the recommended way simply because
+it is easier to edit them.
+
+It is important to follow this specification, because notes will look
+consistently in all languages and will be clearly distinguishable from
+authors' footnotes, if any.  Furthermore, it would be easier to define
+a special @acronym{CSS} class for them, and also to convert the
+translations in other formats such as Texinfo---when these features
+are implemented.
+
address@hidden Credits Slot
address@hidden The Special Slot for Translator's Credits
+
+Most of the translators usually put their name under the translation,
+in the ``footer'' area.  This is entirely acceptable, since some
+readers prefer to send buggestions directly to the translator.  Also,
+giving credit where credit is due is a natural thing.
+
+Like the previous slot, you should ``translate'' it as a @key{SPC} if
+you don't want your name to appear there.
+
+Here is an example of the recommended way to specify credits:
+
address@hidden
+<b>Traduction</b>: Benjamin Drieu 
+<a href="mailto:foo@@example.org";>&lt;foo@@example.org&gt;</a>,
+2007, 2008.
address@hidden example
+
+It is highly desirable to use this form, but you may omit the email
+address or add the homepage of the translator, provided that the
+translation team leader ensures that it constantly meets the linking
+criteria for gnu.org.  Please follow the @acronym{FSF} HTML Style
+Sheet when adding @acronym{URI}s or other information.
+
 @node Migrating
 @subsection Transforming existing translation in PO format