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

[Pavel Kharitonov]

CVSROOT:        /sources/trans-coord
Module name:    trans-coord
Changes by:     Pavel Kharitonov <ineiev>       13/08/30 06:28:19

Modified files:
        gnun/server/gnun: ChangeLog GNUmakefile NEWS 
        gnun/server/gnun/doc: gnun.texi web-trans.texi 

Log message:
        Fix documentation issues reported by Thérèse Godefroy.
        
        * doc/web-trans.texi (Submitting as PO, CSS):
        (Submitting as Plain text, Priorities, Updating, PO Files):
        * doc/gnun.texi (Concepts, Invoking GNUN, Webmaster Tips):
        (report, Main Variables, Sitemap, GNU News):
        (GNUmakefile.team Targets, GNUmakefile.team Cron):
        (New Translation, Wrapping Long Lines, PO Tips, Migrating):
        (Notes Slot): Fixes and rewordings.
        * GNUmakefile (sync): Remove target.
        * doc/gnun.texi (Special Targets): Remove `sync' from the menu.
        (sync): Remove node.
        * NEWS: Update.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/ChangeLog?cvsroot=trans-coord&r1=1.379&r2=1.380
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/GNUmakefile?cvsroot=trans-coord&r1=1.162&r2=1.163
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/NEWS?cvsroot=trans-coord&r1=1.89&r2=1.90
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/doc/gnun.texi?cvsroot=trans-coord&r1=1.88&r2=1.89
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/server/gnun/doc/web-trans.texi?cvsroot=trans-coord&r1=1.55&r2=1.56

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/server/gnun/ChangeLog,v
retrieving revision 1.379
retrieving revision 1.380
diff -u -b -r1.379 -r1.380
--- ChangeLog   19 Aug 2013 07:32:37 -0000      1.379
+++ ChangeLog   30 Aug 2013 06:28:16 -0000      1.380
@@ -1,3 +1,19 @@
+2013-08-30  Pavel Kharitonov  <address@hidden>
+        
+       Fix documentation issues reported by Thérèse Godefroy.
+
+       * doc/web-trans.texi (Submitting as PO, CSS):
+       (Submitting as Plain text, Priorities, Updating, PO Files):
+       * doc/gnun.texi (Concepts, Invoking GNUN, Webmaster Tips):
+       (report, Main Variables, Sitemap, GNU News):
+       (GNUmakefile.team Targets, GNUmakefile.team Cron):
+       (New Translation, Wrapping Long Lines, PO Tips, Migrating):
+       (Notes Slot): Fixes and rewordings.
+       * GNUmakefile (sync): Remove target.
+       * doc/gnun.texi (Special Targets): Remove `sync' from the menu.
+       (sync): Remove node.
+       * NEWS: Update.
+
 2013-08-19  Pavel Kharitonov  <address@hidden>
 
        * doc/web-trans.texi (PO Files): Document that translators

Index: GNUmakefile
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/server/gnun/GNUmakefile,v
retrieving revision 1.162
retrieving revision 1.163
diff -u -b -r1.162 -r1.163
--- GNUmakefile 5 Aug 2013 08:54:33 -0000       1.162
+++ GNUmakefile 30 Aug 2013 06:28:18 -0000      1.163
@@ -1101,51 +1101,6 @@
 vcs-add-always: ;
 endif
 
-# Special target to sync the original English articles from the `www'
-# repository.  It is intended to be invoked by a fencepost cron job
-# and will be useful even when GNUN is deployed.  Automatic adding and
-# removal is not implemented (except adding `verbatim-templates'), so
-# make sure to `cvs add'/`cvs remove' and commit the article when
-# editing gnun.mk.
-wwwdir := $(rootdir)/$(rootdir)/www
-orig-templates := $(addsuffix .html,$(template-translated-base))
-orig-articles := $(addsuffix .html,$(subst /po/,/,$(ALL_BASE)))
-files-to-sync := $(orig-templates) $(orig-articles)
-abs-files-to-sync := $(subst $(rootdir)/,,$(files-to-sync))
-# Templates that are not gettextized, but are necessary to reside in
-# trans-coord for HTML validation at build time.
-verbatim-templates-set := header head-include-1 html5-header \
-  html5-head-include banner footer
-verbatim-templates := $(addprefix server/, \
-  $(foreach template,$(verbatim-templates-set), \
-     $(foreach temp-lang,$(TEMPLATE_LINGUAS),$(template).$(temp-lang).html) \
-   ) \
-  whatsnew.html whatsnew.include)
-
-.PHONY: sync
-sync: 
-# Synchronize all articles and report if an article has been deleted
-# from the master repository.
-       for file in $(abs-files-to-sync) ; do \
-         if [ ! -f $(wwwdir)/$$file ] ; then \
-           echo "Warning: $$file missing in www; update the variable?" \
-           | $(VCSSKIP) mail -s "sync: missing file" $(devel-addr) ; \
-         else \
-           cp -p --update $(wwwdir)/$$file $(rootdir)/$$file ; \
-         fi ; done
-# Copy all necessary templates that are not under GNUN's control and
-# add them if VCS=yes.
-       for t in $(verbatim-templates) ; do \
-         if [ ! -f $(rootdir)/$$t ] ; then \
-           cp -p $(wwwdir)/$$t $(rootdir)/$$t \
-             && $(VCSSKIP) $(vcs) add $(rootdir)/$$t ; \
-         else \
-           cp -p --update $(wwwdir)/$$t $(rootdir)/$$t ; \
-         fi ; done
-       cd $(rootdir) ; \
-         $(VCSSKIP) $(vcs) commit -m \
-         "Automatic sync from the master www repository."
-
 # Assign priorities to translations for report.
 ifdef TEAM
 TEAM-POS := $(sort $(filter %.${TEAM}.po,${ALL_POS}))

Index: NEWS
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/server/gnun/NEWS,v
retrieving revision 1.89
retrieving revision 1.90
diff -u -b -r1.89 -r1.90
--- NEWS        14 Jun 2013 11:54:10 -0000      1.89
+++ NEWS        30 Aug 2013 06:28:18 -0000      1.90
@@ -19,6 +19,8 @@
 *** New option in `gnun-validate-html' to specify emulated Apache
     variables: `--apache-vars'.
 
+*** The support of `sync' target in GNUmakefile is dropped.
+
 ** Bugs fixed in 0.8.
 
 *** `gnun-diff-po' didn't process empty comments correctly.

Index: doc/gnun.texi
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/server/gnun/doc/gnun.texi,v
retrieving revision 1.88
retrieving revision 1.89
diff -u -b -r1.88 -r1.89
--- doc/gnun.texi       21 May 2013 10:18:34 -0000      1.88
+++ doc/gnun.texi       30 Aug 2013 06:28:19 -0000      1.89
@@ -133,7 +133,7 @@
 
 The basic concept behind GNUN is that localization of HTML articles is
 similar to localization of computer address@hidden, it is
-much more closer to localization of software documentation, where
+a lot closer to localization of software documentation, where
 typically strings (also known as ``messages'' in gettext's context) are
 longer than strings in programs.  Nevertheless, all points raised still
 apply.}.  In articles, like in programs, not every string is considered
@@ -187,7 +187,7 @@
 
 First, GNUN extracts all translatable strings from the original English
 article @address@hidden into @address@hidden  The
-resulted file is suitable for manipulation with the various GNU
+resulting file is suitable for manipulation with the various GNU
 @samp{gettext} utilities.  It contains all original article strings and
 all translations are set to empty.  The letter @code{t} in @file{.pot}
 marks this as a Template PO file, not yet oriented towards any
@@ -208,14 +208,6 @@
 dedicated PO files, so called compendia.  @xref{Compendia}, for more
 information.
 
address@hidden
-(FIXME:Translators (but only if we would like to include some
-practical advices to candidate translators on how to join a gnu.org
-translating team)).  You will also find there indications about how to
-contact translating teams, or becoming part of them, for sharing your
-translating concerns with others who target the same native language.
address@hidden ignore
-
 You may use any compatible PO editor to add translated messages into
 the PO file.  @xref{Editing, , Editing, gettext, GNU gettext tools},
 for more information.
@@ -250,7 +242,7 @@
 repository under a special directory @file{po/}, which is a
 sub-directory of the relevant directory in the `www' tree.  So, for
 @indicateurl{http://www.gnu.org/philosophy/free-sw.html} that is
address@hidden/po/}.  Except @file{free-sw.pot}, this directory holds
address@hidden/po/}.  In addition to @file{free-sw.pot}, this directory holds
 the canonical source of every translation, like @file{free-sw.bg.po},
 @file{free-sw.ca.po}, etc. For more details,
 @xref{Files and Directories}.
@@ -436,7 +428,7 @@
 Note that GNUN expects @file{GNUmakefile}, @file{config.mk} and
 @file{gnun.mk} to be @emph{present} under @file{server/gnun} of the
 `www' web repository, otherwise @command{make} has no way to know what
-and how should be built.  Another file, @file{priorities.mk}, is
+to built, and how.  Another file, @file{priorities.mk}, is
 expected to be present under @file{server/gnun} in order to define
 the priorities when reporting about the outdated translations.  If
 absent, the @code{report} target will not sort the translations by
@@ -457,7 +449,7 @@
 will always use the latest versions without the need for any manual
 intervention.
 
-If you are playing with non-gnu.org setup, you also have to take care of
+If you are playing with a non-gnu.org setup, you also have to take care of
 @file{gnun.mk} and put a modified version under @file{server/gnun} of
 your hypothetical tree.  (For gnu.org, that is not necessary since
 a proper @file{gnun.mk} is maintained in `www'.)
@@ -654,7 +646,6 @@
 @menu
 * no-grace-items::
 * update-localized-URLs::
-* sync::
 * report::
 * triggers::
 * validate-all::
@@ -681,49 +672,6 @@
 
 This target is meant to be rebuilt nightly.
 
address@hidden As of Dec 2012 this target doesn't seem to be used very actively;
address@hidden in cron jobs, raw VCS invocations are issued instead.
address@hidden Should we remove it? --- ineiev
address@hidden sync
address@hidden The @code{sync} Target
address@hidden synchronization, repository
-
-The @code{sync} target has a simple task: synchronize the
address@hidden English} articles from a canonical repository, like
-`www'.  It is very important that such synchronization happens,
-because it is desirable to develop the software and add more features
-in a testbed, while the `official instance' operates on the official
-repository in a predictable way.
-
-It is recommended that you `build' the @code{sync} target from a cron
-job, some time before the general build occurs.  That way,
-prerequisites (e.g. original @file{.html} articles) will be updated
-from the canonical repository and the subsequent @command{make}
-invocation, possibly run by cron as well, will update all
-translations.
-
-The @code{VCS} variable affects the behavior: if it is defined to
-`yes' then the synchronized files are committed to the `testing'
-repository, i.e. the @var{destination}.  In addition, if a file meant
-to be synchronized disappeared from the @var{source}, a warning mail
-will be sent to the address defined in the @code{devel-addr} variable
-(defined in @file{gnun.conf}).  The build will continue without
-failure, and will sync and commit all other files, but will send the
-same email message again if the file is still present in the
address@hidden variable during a subsequent invocation.
-
-In addition, @code{sync} synchronizes all ``verbatim'' server templates
-that are not under GNUN's control, such as @file{server/header.html},
address@hidden/banner.html}, @file{server/footer.html} and their
-translations, as defined in the @code{verbatim-templates} variable.
-This is important, as these files may change in the master repository,
-while the validation of the HTML files in the development repository
-will be performed with the old templates expanded, thus making this
-specific test more or less bogus.
-
address@hidden has no effect on this target, as well as
address@hidden
-
 @node report
 @subsection The @code{report} Target
 @cindex reporting
@@ -752,7 +700,7 @@
 all other translations are reported as less important.
 
 There is also a script, @command{gnun-report}, to generate HTML reports.
address@hidden  GNUmakefile.team profides another @code{report}
address@hidden  GNUmakefile.team provides another @code{report}
 target, which produces a more detailed report.
 @xref{report in GNUmakefile.team}.
 
@@ -925,7 +873,7 @@
 @end itemize
 
 This way, the scripts reporting outdated translations and translations
-that hasn't been converted to PO files won't complain about them unless
+that haven't been converted to PO files won't complain about them unless
 the team decides to actually commit @address@hidden
 
 @cindex sitemap
@@ -957,8 +905,8 @@
 @itemx @address@hidden
 A space-separated list of basenames for articles residing in
 @var{directory}, for which POTs will be generated and updated when the
-original article changes.  If an article is missing here, there is no
-way its translations to be maintained via GNUN.
+original article changes.  If an article is missing here,
+GNUN doesn't maintain its translations.
 @end table
 
 @node generic.LANG.html
@@ -1082,7 +1030,7 @@
 articles.
 
 @item
-They mostly consist of links, therefore significant part of their text
+They mostly consist of links, therefore a significant part of their text
 should come to translations without any changes.
 
 @end enumerate
@@ -1096,7 +1044,7 @@
 @file{server/@/gnun/@/compendia/@/address@hidden
 
 Those additional compendia are supposed to be compiled outside of GNUN
-by the same tool that generates the sitemap.  It is responsibility of
+by the same tool that generates the sitemap.  It is the responsibility of
 that tool to provide the compendia with reasonable translations whose
 @code{msgid}s match those generated by PO4A when processing the
 English version of the sitemap.
@@ -1131,8 +1079,8 @@
 localized files.
 
 Note that localized RSS feeds are not supported on purpose, as it would
-be annoying for subscribers if new items appear in English and then once
-again translated.
+be annoying for subscribers if new items appeared in English and then,
+again, as a translation.
 
 @node Team's Repository
 @chapter Maintaining Translations in Your Team's Repository
@@ -1255,7 +1203,7 @@
 
 @item TEAM_URL_PREFIX
 @itemx TEAM_URL_POSTFIX
-These variables are used to transform the path to a file in team's
+These variables are used to transform the path to a file in the team's
 working copy into a URL for this file; they are only needed for
 automatic email notifications.  It is expected that typically
 the URL will point to some sort of Web interface for the repository,
@@ -1380,8 +1328,8 @@
 @file{email-aliases}.  Like @file{nottab}, this file contains lines
 separated by `:'; the lines beginning with `#' are ignored.
 
-The first field is translators' identifier, the second is
-space-separated list of translators' email addresses.  These two
+The first field is the translator's identifier, the second is
+space-separated list of the translator's email addresses.  These two
 fields are mandatory.
 
 @cindex reminder period
@@ -1432,19 +1380,15 @@
 is out of scope of GNUN and this manual.
 
 @item format
-A convenience rule to re-wrap all files upto the standard length.  Most
+A convenience rule to re-wrap all files upto the standard length.  Many
 PO editors leave the @code{msgstr} as a single long line after it has
 been edited, but GNUN will automatically re-wrap the file to the standard
 line length when it is processed.  Wrapping long lines in PO files is a
 good practice as it avoids unnecessary revisions.
 
-This rule checks for all translations that have lines longer than 80,
-and runs @command{msgcat} accordingly to reformat them.  For that
-reason, it is recommended that you wrap all long lines in the comment
-fields (e.g. the file header, including the copyright statement, and any
-other comments for specific messages), because @code{make format} will
-unnecessarily invoke @command{msgcat} for any file that has a longer
-line, wherever it may occur.
+This rule filters all translations with @command{msgcat}; basically,
+it reformats the lines that are longer than the default page width
+of @command{msgcat}.
 
 @item publish
 @anchor{publish}
@@ -1515,7 +1459,7 @@
 @@daily              cd $HOME/projects/address@hidden; make VCS=yes
 @end example
 
-It is not necessary the job to be run on the team leader's machine,
+The job doesn't have to 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
@@ -1564,7 +1508,7 @@
 not yet ``templated'' (i.e. migrated to the new style), or the 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 do what's needed for 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
@@ -1754,8 +1698,8 @@
 @end 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
+language; we use English here, so that everyone understands
+the example.  If you have more notes, each subsequent one should be with
 incremented number, i.e. @samp{TransNote2}, @samp{TransNote3}, etc. and
 you have to add them as more @code{<li>} elements accordingly.
 
@@ -1765,10 +1709,10 @@
 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
+consistent in all languages and will be clearly distinguishable from
+authors' footnotes, if any.  Furthermore, it will be easier to define
 a special CSS class for them, and also to convert the
-translations in other formats such as Texinfo---when these features
+translations in other formats such as Texinfo---when these conversions
 are implemented.
 
 @node Credits Slot
@@ -1809,7 +1753,7 @@
 bothers you, you can ``normalize'' the already finished PO translation
 by executing on the command line @code{msgcat -o @var{file}.po
 @var{file}.po}, before installing it in the repository.  Either way, the
-build system will treat it is a valid PO file.
+build system will treat it as a valid PO file.
 
 For those lucky Emacs users, here is a code snippet that you can put
 in your @file{.emacs}; doing @kbd{M-x po-wrap} while in PO mode will
@@ -1856,7 +1800,7 @@
 @cindex recommendations, PO files
 
 This section contains additional explanations, some in the form of
-advices and recommendations; not all of them are strictly related to
+advice and recommendations; not all of them are strictly related to
 PO files editing.
 
 @itemize
@@ -1898,7 +1842,7 @@
 @item
 Sometimes, especially when the original message contains many links,
 it is easier to copy it to @code{msgstr} and edit the latter by
-translating the English text.  In PO mode, this is done by @kbd{C-j}.
+translating the English text.  In PO mode of Emacs, this is done by @kbd{C-j}.
 This is useful also for large chunks of text in @code{<pre>} elements,
 which normally you would want to preserve verbatim.
 
@@ -1911,7 +1855,7 @@
 @item
 Wrapping of @code{msgstr} using @kbd{M-q} in Emacs (or other means) is
 considered harmful.  It is best to leave GNUN (or more precisely, Po4a)
-to do the wrapping---that way all generated HTML translations will have
+do the wrapping---that way all generated HTML translations will have
 predictable results.  This will help tremendously for the conversion to
 other formats, like Texinfo.  Also, note that not all elements are
 wrapped by default, so deliberately wrapping the text inside the
@@ -1974,8 +1918,8 @@
 facilitate checking.
 
 There is no need to delete the existing HTML translation, GNUN will
-automatically overwrite it.  The only thing a translator should do is to
-commit the PO file in the repository.
+automatically overwrite it.  The only thing a translator should do is
+commit the PO file to the repository.
 
 When an essay has been translated by several people through the years,
 it is important that this information is recorded and reflected in the
@@ -2009,8 +1953,9 @@
 
 First and foremost, respect translators' work---it is ungrateful and
 hard, undoubtedly much harder than translation of programs.  It is
-important to have as many and as better as possible translations, and
-you don't have to make titanic efforts to help.
+important to have as many translations as possible, and make them
+as good as possible, and you don't have to make titanic efforts to
+help.
 
 If you plan to edit a certain page extensively, please do so within a
 reasonable time frame, for example a day or preferably, several hours.

Index: doc/web-trans.texi
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/server/gnun/doc/web-trans.texi,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -b -r1.55 -r1.56
--- doc/web-trans.texi  19 Aug 2013 07:32:32 -0000      1.55
+++ doc/web-trans.texi  30 Aug 2013 06:28:19 -0000      1.56
@@ -250,7 +250,7 @@
 ability) the translation and will install it in the repository.
 
 @item
-In order GNUN to be able to generate (and subsequently update) a fully
+In order for GNUN to be able to generate (and subsequently update) a fully
 translated page, the language should have the server templates
 available as PO files.  These templates are short, and translating them
 shouldn't take much time.  If the language code is present in the
@@ -290,7 +290,7 @@
 the markup of the original article.  Simply save your translation in a
 plain text file (@file{.txt}), preferably in UTF-8 encoding.  You can
 use any decent text editor for that---Emacs, Vim, gEdit, Kate,
-OpenOffice.org (the file should be saved as @file{.txt}, not
+LibreOffice (the file should be saved as @file{.txt}, not
 @file{.odt}), etc.
 
 Translate the title, the blue heading (if it differs slightly from the
@@ -1218,7 +1218,7 @@
 
 @item server/whatsnew.html
 This is ``What's New'', also known as ``GNU's Flashes'', also known as
-``GNU News''.  It is deprecated since quite some time and translating
+``GNU News''.  It has been deprecated for quite some time and translating
 it is discouraged.
 @end table
 
@@ -1254,7 +1254,7 @@
 Nations Manual}.
 
 @item
-GNUmakefile.team also has a means to send a further detalized reports
+GNUmakefile.team also has a means to send more detaled reports
 to specific translators; @pxref{notify in GNUmakefile.team, , , gnun,
 The GNUnited Nations Manual}.  The notification facility takes the
 output of the @code{report} target, adds the URLs of relevant files,
@@ -1477,8 +1477,8 @@
 PO files, @pxref{PO Files, , Working with PO Files, gnun,
 The GNUnited Nations Manual}.}.
 Don't worry, you will soon get accustomed to it.  It is the
-established format for translations in the Free World, and you should
-have no problems if you have translated software before.
+established format for translations in the Free World, and if you 
+have any problems, other translators will help you.
 
 The most efficient way to edit a PO file is using a specialized PO
 editor, because each of them represents and treats gettext messages in
@@ -1763,7 +1763,7 @@
 
 If using the default CSS style for translations does not give the
 expected good results, or there are other problems (significant or not)
-that obstruct reading and/or worsen the look from aesthetic point of
+that obstruct reading or worsen the look from an aesthetic point of
 view, please write to @email{webmasters@@gnu.org} with a description of
 the issue.  If there are several unrelated problems, send separate
 messages with appropriate explanation (which may include a demonstration