CHECK STATE OF TRANSLATION
UPDATE A TRANSLATION
POLICY DURING GDP PROCESS
-MANAGING TRANSLATIONS ON GIT
+MANAGING TRANSLATIONS WITH GIT
+SOME GIT TIPS
DEALING WITH SEVERAL GIT BRANCHES
+GIT PUSH ACCESS
+TECHNICAL BACKGROUND
SOURCES
having experience from lilypond.org translation; see
http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=README;hb=web/master
+If you do not have this experience, you may want to read the first two
+chapters of Git User's Manual at
+http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+
REQUIREMENTS
where <MY-LANGUAGE> is the ISO 639 language code.
Add a language definition for your language in
-buildscripts/langdefs.py.
+python/langdefs.py.
See next section about what files to translate and the following
detailed instructions after the next section.
Word counts (excluding lilypond snippets) are given for each file.
-1- Documentation index and Tutorial
-396 user/lilypond-learning.tely
-5593 user/tutorial.itely
+429 user/lilypond-learning.tely
+6365 user/tutorial.itely
23 user/dedication.itely
-100 user/macros.itexi
-216 index.html.in
-2022 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
-8250 total
+423 user/macros.itexi
+171 index.html.in
+6346 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
+--- ../lilypond-texi2html.init (section TRANSLATIONS)
+13757 total
-2- Introduction and beginning of Application Usage
411 user/preface.itely
-3198 user/introduction.itely
-374 user/lilypond-program.tely
-1477 user/install.itely (partial translation)
-947 user/setup.itely
-2860 user/running.itely
-9267 total
+3855 user/introduction.itely
+407 user/lilypond-program.tely
+1930 user/install.itely (partial translation)
+1149 user/setup.itely
+2827 user/running.itely
+10579 total
-3- Learning manual
-8626 user/fundamental.itely -- Fundamental concepts
-12134 user/tweaks.itely -- Tweaking output
-2985 user/working.itely -- Working on LilyPond files
+10318 user/fundamental.itely -- Fundamental concepts
+14647 user/tweaks.itely -- Tweaking output
+3007 user/working.itely -- Working on LilyPond files
483 user/templates.itely -- Templates
-24228 total
+28455 total
-4- Notation reference
-539 user/lilypond.tely
+695 user/lilypond.tely
91 user/notation.itely -- Musical notation
-2808 user/pitches.itely
-7336 user/rhythms.itely
-1681 user/expressive.itely
-725 user/repeats.itely
-916 user/simultaneous.itely
-1861 user/staff.itely
-879 user/editorial.itely
-2336 user/text.itely
-54 user/specialist.itely -- Specialist notation
-2630 user/vocal.itely
-1275 user/chords.itely
+3123 user/pitches.itely
+5013 user/rhythms.itely
+1146 user/expressive.itely
+555 user/repeats.itely
+1455 user/simultaneous.itely
+1701 user/staff.itely
+895 user/editorial.itely
+2286 user/text.itely
+76 user/specialist.itely -- Specialist notation
+2670 user/vocal.itely
+1464 user/chords.itely
702 user/piano.itely
-481 user/percussion.itely
+810 user/percussion.itely
826 user/guitar.itely
66 user/strings.itely
242 user/bagpipes.itely
-4289 user/ancient.itely
-2458 user/input.itely -- Input syntax
+4487 user/ancient.itely
+5805 user/input.itely -- Input syntax
2164 user/non-music.itely -- Non-musical notation
-8399 user/spacing.itely -- Spacing issues
-5149 user/changing-defaults.itely -- Changing defaults
-4547 user/programming-interface.itely -- Interfaces for programmers
-935 user/notation-appendices.itely -- Notation manual tables
+8451 user/spacing.itely -- Spacing issues
+11391 user/changing-defaults.itely -- Changing defaults
+5202 user/programming-interface.itely -- Interfaces for programmers
+1190 user/notation-appendices.itely -- Notation manual tables
250 user/cheatsheet.itely -- Cheat sheet
-53639 total
+62756 total
-5- Application usage
-2917 user/lilypond-book.itely -- LilyPond-book
-975 user/converters.itely -- Converting from other formats
-3892 total
+3248 user/lilypond-book.itely -- LilyPond-book
+1171 user/converters.itely -- Converting from other formats
+4419 total
-6- Appendices whose translation is optional
-299 user/literature.itely
+310 user/literature.itely
960 user/scheme-tutorial.itely (needs to be revised first)
-1259 total
+1270 total
TRANSLATION DETAILED INSTRUCTIONS
@c KEEP LY
-Otherwise the music snippet would be reset to the same contents as the
+Otherwise the music snippet would be reset to the same content as the
English version at next 'make snippet-update' run (see UPDATING A
TRANSLATION below).
make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'
+To avoid printing terminal colors control characters, which is often
+desirable when you redirect output to a file, run
+
+ make ISOLANG=<MY_LANGUAGE> NO_COLOR=1 check-translation
+
Global state of the translation is recorded in
Documentation/translations.html.in, which is used to generate
Updating music snippets can quickly become cumbersome, as most
snippets should be identical in all languages. Fortunately, there is
-a script than can do this odd job for you (run from Documentation):
+a script that can do this odd job for you (run from Documentation):
make ISOLANG=<MY_LANGUAGE> snippet-update
with music snippets from user/every.itely. It ignores skeleton files,
and keeps intact music snippets preceded with a line starting with '@c
KEEP LY'; it reports an error for each .itely that has not the same
-music snippet count in both languages.
+music snippet count in both languages. Always use this script with a
+lot of care, i.e. run it on a clean Git working tree, and check the
+changes it made with "git diff" before committing; if you don't do so,
+some @lilypond snippets might be broken or make no sense in their
+context.
Finally, a command runs the three update processes above for all
enabled languages (from Documentation):
game is catching where has gone each section. In Learning manual, and
in Notation Reference sections which have been revised in GDP, there
may be completely new sections: in this case, copy @node and
-@section-command from English docs, and put the usual tricky line
-'UNTRANSLATED NODE: IGNORE ME'. Note that it is not possible to
-exactly match subsections or subsubsections of documentation in
-English, when contents has been deeply revised; in this case, kee
-obsolete (sub)subsections in the translation.
+@section-command from English docs, and add the marker for
+untranslated status '@untranslated' on a single line. Note that it is
+not possible to exactly match subsections or subsubsections of
+documentation in English, when contents has been deeply revised; in
+this case, keep obsolete (sub)subsections in the translation, marking
+them with a line '@c obsolete' just before the node.
+
+4) update sections finished in GDP; check sections status at GDP website.
-* Hints for Emacs users (without Emacs AucTeX installed)
-Texinfo Emacs mode makes this step easier:
+* Hints for Emacs users
+
+Emacs with Texinfo mode makes this step easier:
+
+- without Emacs AucTeX installed, C-c C-s shows structure of current
+Texinfo file in a new buffer *Occur*; to show structure of two files
+simultaneously, first split Emacs window in 4 tiles (with C-x 1 and
+C-x 2), press C-c C-s to show structure of one file (e.g. the translated
+file), copy *Occur* contents into *Scratch*, then press C-c C-s for the
+other file.
+If you happen to have installed AucTeX, you can either call the macro
+by doing M-x texinfo-show-structure or create a key binding in your
+~/.emacs, by adding the four following lines:
+ (add-hook 'Texinfo-mode-hook
+ '(lambda ()
+ (define-key Texinfo-mode-map "\C-cs"
+ 'texinfo-show-structure)))
+and then obtain the structure in the *Occur* buffer with C-c s
-- C-c C-s shows structure of current Texinfo file in a new buffer
-*Occur*; to show structure of two files simultaneously, first split
-Emacs window in 4 tiles (with C-x 1 and C-x 2), press C-c C-s to
-show structure of one file (e.g. the translated file), copy *Occur*
-contents into *Scratch*, then press C-c C-s for the other file.
- Do not bother updating @menus when all menu entries are in the same
file ; make sure there is at least a (possibly empty) @menu block
everywhere it is needed, then do C-c C-u C-a ("update all menus") when
you have updated all the rest of the file.
+- Moving to next or previous node: press C-s and type node (or C-s
+@node if the text contains the word 'node') then press C-s to move to
+next node or C-r to move to previous node. Similar operation can be
+used to move to the next/previous section.
+
+- Moving a whole node (or even a sequence of nodes): jump to beginning
+of the node (quit incremental search by pressing an arrow), press
+C-SPACE, press C-s node and repeat C-s until you have selected enough
+text, cut it with C-w or C-x, jump to the right place (moving between
+nodes with the previous hint is often useful) and paste with C-y or
+C-v.
+
4) update documentation PO. Unless you have special interest in
having all titles translated in the next development release, it is
documentation sectioning has been revised in one go, so all this
maintenance plan has to be repeated whenever a big reorganization is
made. Currently (in May 2008), only chapters 3-7 in Notation Reference
-and Application Usage have not be reorganized yet.
+and Application Usage have not been reorganized yet.
- This just makes translated documentation take advantage of the new
organization, which is far better than the old one.
texi2html and node names are directly translated in source files.
-MANAGING TRANSLATIONS ON GIT
+MANAGING TRANSLATIONS WITH GIT
This policy explains how to manage Git branches and commit
translations to Git.
PROCESS'.
+SOME GIT TIPS
+
+* Saving uncommited changes in the working tree:
+
+ git diff > foo.diff
+
+This does not save untracked or ignored files. If you prefer to
+include changes added to the index with 'git add', replace 'git diff'
+with 'git diff HEAD'.
+Then, you may try to apply foo.diff on a source tree with
+
+ patch -p1 < foo.diff
+
+
DEALING WITH SEVERAL GIT BRANCHES
* It is possible to work with several branches on the same local Git
Note that it is possible to check out another branch while having
uncommitted changes, but it is not recommended unless you know what
you are doing; it is recommended to run 'git status' to check this
-kind of issue before checking ouy another branch.
+kind of issue before checking out another branch.
When pulling using SHORTHAND, do not forget to check first that the
right branch is checked out, i.e. the branch named A in the first part
delete...) on these branches, but this possibility is not detailed
here.
+Note that when you push BRANCH from SUBDIR to the main repository,
+and BRANCH is checked out in the main repository, you must save
+uncommitted changes (see SOME GIT TIPS) and do 'git reset --hard' in
+the main repository in order to apply pushed changes in the working
+tree of the main repository.
+
+
+GIT PUSH ACCESS
+
+If you have permission to push to Git with login USER, please start a
+new Git repository from scratch to avoid polluting history with
+duplicate commits; follow the usual instructions, except that every
+file you write in .git/remotes should contain instead
+
+URL: ssh://USER@git.sv.gnu.org/srv/git/lilypond.git
+Push: BRANCH:refs/heads/BRANCH
+Pull: BRANCH:refs/remotes/origin/BRANCH
+
+Then, you can use .git/remotes/NAME to push BRANCH with
+
+ git push NAME
+
+which works regardless of the branch checked out.
+
TECHNICAL BACKGROUND
A number of Python scripts handle a part of the documentation
-translation process. All are located in buildscripts/, except
-langdefs.py which is in python/
+translation process.
+All scripts used to maintain the translations
+are located in scripts/aux/:
-* buildlib.py -- module containing common functions (read piped output
-of a shell command, use Git)
-* langdefs.py -- language definitions module
* check_translation.py -- show diff to update a translation
* texi-langutils.py -- quickly and dirtily parse Texinfo files to
make message catalogs and Texinfo skeleton files
* texi-skeleton-update.py -- update Texinfo skeleton files
+* update-snippets.py -- synchronize ly snippets with those from
+English docs
+* translations-status.py -- update translations status pages and word
+counts in the file you are reading.
+* tely-gettext.py -- gettext node names, section titles and references
+in the sources; WARNING only use this script when support for
+"makeinfo --html" has been dropped.
+
+Other scripts are used in the build process, in scripts/build/:
* html-gettext.py -- translate node names, section titles and cross
references in HTML files generated by makeinfo
-* add_html_footer.py (module imported by www_post.py) -- add footer and
-tweak links in HTML pages
* texi-gettext.py -- gettext node names, section titles and references
before calling texi2pdf
* mass-link.py -- link or symlink files between English documentation
and documentation in other languages
-* update-snippets.py -- synchronize ly snippets with those from
-English docs
-* translations-status.py -- update translations status pages and word
-counts in the file you are reading.
+
+Python modules used by scripts in scripts/aux/ or scripts/build/ (but
+not by installed Python scripts) are located in python/aux/:
+* manuals_definitions.py -- define manual names and name of
+cross-reference Texinfo macros
+* buildlib.py -- common functions (read piped output
+of a shell command, use Git)
+* postprocess_html.py (module imported by www_post.py) -- add footer and
+tweak links in HTML pages
+
+And finally
+* python/langdefs.py -- language definitions module
projects / lilypond.git / blobdiff