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

[Yavor Doganov]

CVSROOT:        /sources/trans-coord
Module name:    trans-coord
Changes by:     Yavor Doganov <yavor>   08/03/13 17:07:40

Modified files:
        gnun/server/gnun: ChangeLog gnun.texi 
Added files:
        gnun/server/gnun: GNUmakefile.team 

Log message:
        * GNUmakefile.team: New file to facilitate team work.
        * gnun.texi (PO Files and Team, GNUmakefile.team Variables)
        (GNUmakefile.team and Cron): New nodes.
        (Disadvantages): Delete the item about team work; no longer a
        disadvantage.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/ChangeLog?cvsroot=trans-coord&r1=1.33&r2=1.34
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/gnun.texi?cvsroot=trans-coord&r1=1.13&r2=1.14
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/GNUmakefile.team?cvsroot=trans-coord&rev=1.1

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/server/gnun/ChangeLog,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -b -r1.33 -r1.34
--- ChangeLog   13 Mar 2008 09:18:00 -0000      1.33
+++ ChangeLog   13 Mar 2008 17:07:40 -0000      1.34
@@ -1,5 +1,11 @@
 2008-03-13  Yavor Doganov  <address@hidden>
 
+       * GNUmakefile.team: New file to facilitate team work.
+       * gnun.texi (PO Files and Team, GNUmakefile.team Variables)
+       (GNUmakefile.team and Cron): New nodes.
+       (Disadvantages): Delete the item about team work; no longer a
+       disadvantage.
+
        * GNUmakefile (check-po): Use a temporary variable PO, defined for
        each sub-shell invocation.
        ($(template_dir)/po/%.$(1).po): Prepend and define the PO variable.

Index: gnun.texi
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/server/gnun/gnun.texi,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -b -r1.13 -r1.14
--- gnun.texi   9 Mar 2008 20:45:06 -0000       1.13
+++ gnun.texi   13 Mar 2008 17:07:40 -0000      1.14
@@ -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 09.03.2008
address@hidden lastupdate 13.03.2008
 @afourpaper
 @c %**end of header
 
@@ -358,12 +358,6 @@
 have to wait for a day until their PO files are updated, and another
 day for the @address@hidden articles to get generated, after
 they commit the updated POs.
-
address@hidden
-Currently there is no way a translation team can take advantage of
address@hidden while following their own translation process, because
-the suite is tied to the official repository.  We hope that we will
-resolve this problem soon.
 @end itemize
 
 @node Usage
@@ -718,6 +712,8 @@
                           format under @acronym{GNUN}'s control.
 * generic.LANG.html::   Specifying information that will propagate in
                           every translation in a certain language.
+* PO Files and Team::   How to maintain translations in the team's
+                          repository.
 @end menu
 
 @node New Translation
@@ -1062,6 +1058,192 @@
 @address@hidden, including the homepage), will be modified to
 include the contents of this special file.
 
address@hidden PO Files and Team
address@hidden Maintaining Translations in Your Team's Repository
+
address@hidden operates on the ``official'' Web repository of the
+Savannah project `www', where normally only the coordinators of
+translation teams have write access.  However, all translation teams
+have their own projects, so it is possible to take advantage of Savannah
+as a hosting facility to make the team work more comfortable.
+
+The PO files provide an excellent and natural way to review each other's
+translations, because the translation appears right below the original
+message.  Mutual reviews and proof-reading of translations is a crucial
+part of the process.  Furthermore, team work is great for the community
+spirit; automating some of the operations also result in more time for
+all members to concentrate on the important tasks.
+
+The file @file{gnun/server/gnun/GNUmakefile.team} in the Sources
+repository of the `trans-coord' project is a template, aimed for all
+translation teams who wish to use their own project's repository as a
+place to keep their draft translations, until they ripe and are ready
+to be installed officially.
+
+The following diagram illustrates a typical workflow---it is applicable
+for small, medium and large teams:
+
address@hidden
address@hidden
++----------+                   +-------------------+
+| ``www''  |                   |   address@hidden''    |
+|   Web    |------>---->-------|Sources repository |
+|repository|  automatic merge  +-------------------+
++----------+                         |    |     |
+     |                               |    |     `-- Member A
+     +------------<----<-------------'    |
+                  Leader                  `---Member B
address@hidden group
address@hidden example
+
+All members and the team leader(s) commit in their project's
+repository---when a translation is ready, the leader checks it in in the
+official `www' repository.  If an original article changes,
+a build could be invoked to synchronize (i.e. merge) the changes and
+optionally automatically commit them so that the draft PO files are
+updated.  A translator would then normally update the PO file, and
+commit it again in the project's Sources repository, from where the
+coordinator will pick it up and install it in `www'.
+
+To take advantage of this semi-automation, rename this template
address@hidden as @file{GNUmakefile} and install it in the root
+of your project's Sources repository.  Then create directories and
+sub-directories exactly as they are in `www'.  Do not create the
address@hidden/po} sub-directories; they are redundant here.  Instead, install
+the PO files in the normal locations where the corresponding
address@hidden@var{lang}.html} resides in `www', for example:
+
address@hidden
address@hidden
+Root
+  |
+  |--GNUmakefile
+  |address@hidden
+  |address@hidden
+  |--gnu
+  |   |
+  |   |
+  |   address@hidden
+  |   address@hidden
+  |   address@hidden
+  |
+  |
+  +--philosophy
+  |     |
+  |     |
+  |     address@hidden
+  |     address@hidden
+  |     address@hidden
+  |     address@hidden
+  |
+  address@hidden
address@hidden group
address@hidden example
+
+The next sections explain how to adopt the makefile for your team and
+how to invoke a ``build''.
+
address@hidden
+* GNUmakefile.team Variables::
+* GNUmakefile.team and Cron::
address@hidden menu
+
address@hidden GNUmakefile.team Variables
address@hidden Adopting @file{GNUmakefile.team} For a Specific Team
+
+To adjust the makefile for your team, you need to edit two variables.
+
address@hidden @samp
address@hidden TEAM
+Set this to the language code, like @code{bg} or @code{pt-br}.
+
address@hidden wwwdir
+The relative path to the working copy of the master `www' repository.
+So if you have checked out your project's Sources repository at
address@hidden/projects/address@hidden and the `www' Web repository at
address@hidden/projects/www}, the value of @code{wwwdir} should be
address@hidden/www/}.  Note the slash at the end, it is important.
address@hidden table
+
+Technically speaking, two variants of one language sharing the same
+project and repository (such as @code{zh-cn} and @code{zh-tw}) are not
+supported---patches welcome.  As a workaround, there could be two
+directories with two @file{GNUmakefile}s and each directory having its
+own tree.
+
+Some variables are specified on the command line, and alter the behavior
+of the build process.
+
address@hidden @samp
address@hidden VERBOSE=yes
+Print more information from @command{cvs} and @command{msgmerge}; off by
+default.  Note that @code{VERBOSE} can be defined to any string, it will
+have the same effect.
+
address@hidden VCS=yes
+Update both `www' and address@hidden' repositories, then commit the
+merged PO files in the latter repository.  By default, there is no CVS
+interaction.
address@hidden table
+
address@hidden Targets in @file{GNUmakefile.team}
+
address@hidden @code
address@hidden update
+Updates the repositories.  Does nothing unless @code{VCS=yes}.
+
address@hidden sync
+Merges all available PO files from the corresponding POT in `www'.
+
address@hidden report
+Verifies which translations are complete, and prints a list (with
+statistics) of those that need to be updated.
address@hidden table
+
address@hidden VCS=yes} is the recommended command to be run
+periodically.  To check the status of the translations, run
address@hidden report}.
+
+Feel free to replace all strings with equivalents in your native
+language and of course---do not hesitate to extend this file and modify
+it as much as you like.  For example, useful extra functionality would
+be a target that will check which files have not yet been committed in
+the official repository, or which files have to be updated there
+(i.e. they were updated by the team members but not installed by the
+coordinator).  Either way, if you come up with something interesting, it
+would be nice to send a message to @email{trans-coord-devel@@gnu.org},
+so that @file{GNUmakefile.team} gets updated for all teams' benefit.
+
address@hidden GNUmakefile.team and Cron
address@hidden Automatic Synchronization and Status Reports
+
+It is convenient to invoke such synchronization automatically, for
+example once every day.  If you have enabled commit notifications for
+the project's repository, any new changes will be visible for
+subscribers.  Here is an example crontab entry:
+
address@hidden
+# m h  dom mon dow   command
+@@daily              cd $HOME/projects/address@hidden ; make VCS=yes
address@hidden example
+
+It is not necessary the job to be run on the team leader's machine,
+since all team members have write access to their project repository.
+
+If desired, you could set up another job to report the status of the
+translations weekly or fortnightly, for example:
+
address@hidden
+# m h  dom mon dow   command
+@@weekly             cd $HOME/projects/address@hidden ; \
+                       make report | mail -s "Weekly statistics" \
+                       address@hidden@@gnu.org
address@hidden example
+
address@hidden:} Most cron implementations do not allow the character
+`\' as a line continuation character---the example shown is made that
+way for better readability.
+
 @node Internals
 @chapter Unexciting Information for @acronym{GNUN}'s Operation
 

Index: GNUmakefile.team
===================================================================
RCS file: GNUmakefile.team
diff -N GNUmakefile.team
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ GNUmakefile.team    13 Mar 2008 17:07:40 -0000      1.1
@@ -0,0 +1,94 @@
+# This is -*-makefile-gmake-*-, because we adore GNU make.
+# Copyright (C) 2008 Free Software Foundation, Inc.
+
+# This file is part of GNUnited Nations.
+
+# GNUnited Nations is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+
+# GNUnited Nations is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with GNUnited Nations.  If not, see <http://www.gnu.org/licenses/>.
+
+########################################################################
+### TRANSLATORS: Rename this file as GNUmakefile and install it in the #
+### root of your project's *Sources* repository.  For details, see the #
+### section "PO Files and Team" in the manual.                         #
+########################################################################
+
+### DEPENDENCIES ###
+# GNU make >= 3.81 (prereleases are OK too)
+# GNU gettext >= 0.14
+# CVS
+
+SHELL = /bin/bash
+
+# Set this variable to your language code.
+TEAM := bg
+
+# The relative path to the working copy of the master "www"
+# repository; must end with a trailing slash.
+wwwdir := ../www/
+
+# Adjust these variables if you don't have the programs in your PATH.
+MSGMERGE := msgmerge
+MSGFMT := msgfmt
+CVS := cvs
+
+translations := $(shell find -name '*.$(TEAM).po' | sort)
+
+# For those who love details.
+ifdef VERBOSE
+$(info translations = $(translations))
+MSGMERGEVERBOSE := --verbose
+ECHO := echo $$file: ;
+CVSQUIET :=
+endif
+
+# If not in VERBOSE mode, suppress the output from cvs.
+CVSQUIET ?= -q
+
+# The command to update the repositories.
+define cvs-update
+$(CVS) $(CVSQUIET) update -d -P
+endef
+
+.PHONY: all
+all: update sync
+
+# Update the master and the team repositories.
+.PHONY: update
+update:
+ifeq ($(VCS), yes)
+       @echo Updating the repositories...
+       cd $(wwwdir) && $(cvs-update)
+       $(cvs-update)
+else
+       $(info Repositories were not updated, you might want "make VCS=yes".)
+endif
+
+# Synchronize (update) the PO files from the master POTs.
+.PHONY: sync
+sync: update
+       @for file in $(translations) ; do \
+         $(ECHO) $(MSGMERGE) $(MSGMERGEVERBOSE) --quiet --update $$file \
+         $(wwwdir)`dirname $$file`/po/`basename $${file/.$(TEAM).po/.pot}` ; \
+       done
+ifeq ($(VCS),yes)
+       $(CVS) commit -m "Automatic merge from the master repository."
+endif
+
+# Helper target to check which articles have to be updated.
+.PHONY: report
+report:
+       @for file in $(translations) ; do \
+         LC_ALL=C $(MSGFMT) --statistics -o /dev/null $$file 2>&1 \
+           | egrep '(fuzzy|untranslated)' \
+             && echo "$${file#./} needs updating." || true ; \
+       done