LILYPOND DOCUMENTATION TRANSLATION
+TABLE OF CONTENTS
SOURCES
+GIT
+REQUIREMENTS
+WHICH DOCUMENTATION CAN BE TRANSLATED
+STARTING A TRANSLATION IN A NEW LANGUAGE
+FILES TO BE TRANSLATED
+TRANSLATION DETAILED INSTRUCTIONS
+* LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION
+* REFERENCE NOTATION AND PROGRAM USAGE MANUAL
+* DOCUMENTATION INDEX index.html.in
+CHECK STATE OF TRANSLATION
+UPDATE A TRANSLATION
+POLICY DURING GDP PROCESS
+MANAGING TRANSLATIONS WITH GIT
+SOME GIT TIPS
+DEALING WITH SEVERAL GIT BRANCHES
+GIT PUSH ACCESS
+TECHNICAL BACKGROUND
-The sources live in a GIT repository. Git 1.4.4.1 or newer is
-required, and Git 1.5.x is highly recommended. To get a fresh version
-of LilyPond sources run
- mkdir lily ; cd lily
- git init-db
- git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/lilypond/translation:lilypond/translation
- git checkout -b mytranslations lilypond/translation
+SOURCES
+
+The sources live in a GIT repository. Git 1.5.x is required, and
+latest version available on your platform is always recommended. To
+get a fresh version of LilyPond sources run
+
+ mkdir lily ; cd lily ; git init-db ; mkdir .git/remotes
+
+then write the two following lines to a text file named .git/remotes/trans
+
+URL: git://git.sv.gnu.org/lilypond.git/
+Pull: lilypond/translation:refs/remotes/origin/lilypond/translation
+
+then run
+
+ git fetch trans
+ git checkout -b lilypond/translation origin/lilypond/translation
GIT
Documentation/<LANG>/foo/bar.
Unmentioned files should not be translated.
-Priorities: 1. delivery, 2. 3. 4. 5. later, 6. optional.
+Priorities:
+ 1. delivery
+ 2. 3. 4. 5. later
+ 6. optional
Files marked with priority 3, 4 or 5 may be submitted individually.
-
--1- Documentation index, Tutorial and Cheat Sheet
-1 user/lilypond.tely
-1 user/tutorial.itely
-1 user/dedication.itely
-1 user/cheatsheet.itely
-1 index.html.in
- po/<MY-LANGUAGE>.po
-
-In addition, user/macros.itexi may be translated in case typographic
-rules used in this file are different in your language.
-
--2- User manual introduction
-2 user/preface.itely
-2 user/introduction.itely
+Word counts (excluding lilypond snippets) are given for each file.
+
+-1- Documentation index and Tutorial
+412 user/lilypond-learning.tely
+5652 user/tutorial.itely
+23 user/dedication.itely
+378 user/macros.itexi
+218 index.html.in
+3457 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
+10140 total
+
+-2- Introduction and beginning of Application Usage
+411 user/preface.itely
+3704 user/introduction.itely
+390 user/lilypond-program.tely
+1674 user/install.itely (partial translation)
+947 user/setup.itely
+2879 user/running.itely
+10005 total
-3- Learning manual
-3 user/putting.itely -- Putting it all together
-3 user/working.itely -- Working on LilyPond files
-3 user/tweaks.itely -- Tweaking output
+9800 user/fundamental.itely -- Fundamental concepts
+12228 user/tweaks.itely -- Tweaking output
+3005 user/working.itely -- Working on LilyPond files
+483 user/templates.itely -- Templates
+25516 total
-4- Notation reference
-4 user/basic-notation.itely -- Basic notation
-4 user/instrument-notation.itely -- Instrument-specific notation
-4 user/advanced-notation.itely -- Advanced notation
-4 user/changing-defaults.itely -- Changing defaults
-4 user/non-music.itely -- Non-musical notation
-4 user/spacing.itely -- Spacing issues
-4 user/programming-interface.itely -- Interfaces for programmers
-4 user/scheme-tutorial.itely -- Scheme tutorial
-
--5- Program usage
-5 user/lilypond-program.tely
-5 user/install.itely -- How to install or compile
-5 user/running.itely -- Running LilyPond
-5 user/lilypond-book.itely -- LilyPond-book
-5 user/converters.itely -- Converting from other formats
+544 user/lilypond.tely
+91 user/notation.itely -- Musical notation
+2822 user/pitches.itely
+6591 user/rhythms.itely
+944 user/expressive.itely
+976 user/repeats.itely
+1078 user/simultaneous.itely
+2310 user/staff.itely
+827 user/editorial.itely
+1851 user/text.itely
+68 user/specialist.itely -- Specialist notation
+2745 user/vocal.itely
+1530 user/chords.itely
+702 user/piano.itely
+546 user/percussion.itely
+826 user/guitar.itely
+66 user/strings.itely
+242 user/bagpipes.itely
+3474 user/ancient.itely
+4971 user/input.itely -- Input syntax
+2164 user/non-music.itely -- Non-musical notation
+8400 user/spacing.itely -- Spacing issues
+6951 user/changing-defaults.itely -- Changing defaults
+5213 user/programming-interface.itely -- Interfaces for programmers
+894 user/notation-appendices.itely -- Notation manual tables
+250 user/cheatsheet.itely -- Cheat sheet
+57076 total
+
+-5- Application usage
+3175 user/lilypond-book.itely -- LilyPond-book
+975 user/converters.itely -- Converting from other formats
+4150 total
-6- Appendices whose translation is optional
-6 user/literature.itely
-6 user/templates.itely
-6 user/notation-appendices.itely
-
-* WORD COUNTS FOR CATEGORIES
-
-LANG=C wc --words $(grep ^1 TRANSLATION | cut -d ' ' -f 2)
- 777 user/lilypond.tely
- 6322 user/tutorial.itely
- 63 user/dedication.itely
- 632 user/cheatsheet.itely
- 361 index.html.in
- 8155 total
-
-LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2)
- 451 user/preface.itely
- 4170 user/introduction.itely
- 4621 total
-
-LANG=C wc --words $(grep ^3 TRANSLATION | cut -d ' ' -f 2)
- 2230 user/putting.itely
- 3232 user/working.itely
- 2327 user/tweaks.itely
- 7789 total
-
-LANG=C wc --words $(grep ^4 TRANSLATION | cut -d ' ' -f 2)
- 12391 user/basic-notation.itely
- 15779 user/instrument-notation.itely
- 9530 user/advanced-notation.itely
- 7386 user/changing-defaults.itely
- 3884 user/non-music.itely
- 8318 user/spacing.itely
- 4781 user/programming-interface.itely
- 915 user/scheme-tutorial.itely
- 62984 total
-
-LANG=C wc --words $(grep ^5 TRANSLATION | cut -d ' ' -f 2)
- 3566 user/running.itely
- 3549 user/lilypond-book.itely
- 1062 user/converters.itely
- 8177 total
-
-LANG=C wc --words $(grep ^6 TRANSLATION | cut -d ' ' -f 2)
- 339 user/literature.itely
- 4648 user/templates.itely
- 836 user/notation-appendices.itely
- 5823 total
+299 user/literature.itely
+960 user/scheme-tutorial.itely (needs to be revised first)
+1259 total
TRANSLATION DETAILED INSTRUCTIONS
All files should be encoded in UTF-8.
-* USER MANUAL
+* LEARNING MANUAL AND OTHER TEXINFO DOCUMENTATION
Any title which comes with one of the following commands must not be
translated directly in the Texinfo source
This .po file should be in Documentation/po.
+Take care of using typographic rules for your language, especially in
+user/macros.itexi.
+
+
Please keep verbatim copies of music snippets (in @lilypond blocs).
However, some music snippets containing text that shows in the
rendered music, and sometimes translating this text really helps the
@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).
+When you encounter
+
+ @lilypondfile[<number of fragment options>,texidoc]{FILENAME.ly}
+
+in the source, open input/lsr/FILENAME.ly, translate the `texidoc'
+header field it contains, enclose it with 'texidoc<MY-LANGUAGE> = "'
+and '"', and write it into input/texidocs/FILENAME.texidoc -- please
+keep possibly existing translations in other languages!
+Additionnally, you may translate the snippet's title in `doctitle'
+header field, in case `doctitle' is a fragment option used in
+@lilypondfile; you can do this exactly the same way as `texidoc'. For
+instance, input/texidocs/FILENAME.texidoc may contain
+
+doctitlees = "Spanish title baz"
+texidoces = "
+Spanish translation blah
+"
+doctitlede = "German title bar"
+texidocde = "German translation foo
+"
+
@example blocs need not be verbatim copies, e.g. variable names,
file names and comments should be translated.
lilypond-devel@gnu.org.
-* PROGRAM USAGE MANUAL
+* REFERENCE NOTATION AND PROGRAM USAGE MANUAL
-Copy user/lilypond-program.tely into <MY-LANGUAGE>/user, then
-translate this file and run skeleton-update (see UPDATE A TRANSLATION
-below). Your are now ready to translate program usage manual exactly
-like the user manual.
+Copy user/lilypond.tely (or user/lilypond-program.tely, respectively)
+into <MY-LANGUAGE>/user, then translate this file and run
+skeleton-update (see UPDATE A TRANSLATION below). Your are now ready
+to translate notation reference (program usage manual, respectively)
+exactly like the learning manual.
* DOCUMENTATION INDEX index.html.in
make ISOLANG=<MY_LANGUAGE> check-translation
This presents a diff of the original files since the most recent
-revision of the translation. To check a single file, run
+revision of the translation. To check a single file, cd into
+Documentation and run
+
+ make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely check-translation
+
+
+Small tip: to see only which files need to be updated, do
+
+ make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'
+
- python buildscripts/check_translation.py Documentation/<MY-LANGUAGE>/user/foo.itely
+Global state of the translation is recorded in
+Documentation/translations.html.in, which is used to generate
+Translations status page. To update that page, do from Documentation/
+ make translation-status
+
+This will also leave out/translations-status.txt, which contains
+up-to-dateness percentages for each translated file, and update word
+counts of documentation files in this file.
UPDATE A TRANSLATION
+Instead of running check-translation, you can run update-translation,
+which will run your favorite text editor to update files. First, make
+sure environment variable EDITOR is set to a text editor command, then
+run from Documentation
+
+ make ISOLANG=<MY-LANGUAGE> update-translation
+
+or to update a single file
+
+ make CHECKED_FILES=<MY-LANGUAGE>/user/foo.itely update-translation
+
+For each file to be udpated, update-translation will open your text
+editor with this file and a diff of the file in English; if the diff
+cannot be generated or is bigger than the file in English itself, the
+full file in English will be opened instead.
+
Texinfo skeleton files, i.e. .itely files not yet translated,
containing only the Texinfo structure can be updated automatically:
whenever 'make check-translation' shows that such files should be
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
make all-translations-update
-This command is mainly intended to be used by the Translation meister.
+Use this command with caution, and keep in mind it will not be really
+useful until translations are stabilized after the end of GDP.
+
+
+POLICY DURING GDP PROCESS
+or "How to maintain translations without updating them"
+
+During GDP progress, documentation changes so much, and translators are
+often involved in GDP too, so keeping translations up to date is very
+difficult. However, it is possible -- and even recommended -- to
+perform some maintaining that keeps translated documentation usable
+and eases future translation updating. The rationale below the tasks
+list motivates this plan.
+
+The following tasks are listed in decreasing priority order.
+
+1) Update macros.itexi. For each obsolete macro definition, if it is
+possible to update macro usage in documentation with an automatic text
+or regexp substitution, do it and delete the macro definition from
+macros.itexi; otherwise, mark this macro definition as obsolete with a
+comment, and keep it in macros.itexi until the documentation
+translation has been updated and no longer uses this macro.
+
+2) Update *.tely files completely with make check-translation -- you
+may want to redirect ouptput to a file because of overwhelming output,
+or call check-translation.py on individual files, see CHECK STATE OF
+TRANSLATION.
+
+3) in .itelys, match sections and .itely file names with those from
+English docs, which possibly involves moving nodes contents in block
+between files, without updating contents itself. In other words, the
+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.
+
+* Hints for Emacs users (without Emacs AucTeX installed)
+
+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
+
+
+- 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
+better to wait until step 3) has been completed, to avoid doing the
+work more than once.
+
+5) Fix broken cross-references by running (from Documentation/)
+
+ make ISOLANG=<YOUR-LANGUAGE> fix-xrefs
+
+This step requires a sucessful documentation build (with 'make web').
+Some cross-references are broken because they point to a node that
+exists in the documentation in English, which has not been added to
+the translation; in this case, do not fix the cross-reference but keep
+it "broken", so that the resulting HTML link will point to an existing
+page of documentation in English.
+
+Rationale
+
+You may wonder if it would not be better to leave translations as-is
+until you can really start updating translations. There are several
+reasons to do these maintenance tasks right now.
+
+- This will have to be done sooner or later anyway, before updating
+translation of documentation contents, and this can already be done
+without needing to be redone later, as sections of documentation in
+English are mostly revised once. However, note that not all
+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 been reorganized yet.
+
+- This just makes translated documentation take advantage of the new
+organization, which is far better than the old one.
+
+- Moving and renaming sections to match sectioning of documentation in
+English simplify future updating work: it allows updating the
+translation by side-by-side comparison, without bothering whether
+cross-reference names already exist in the translation.
+
+- Each maintenance task (except 4) updating PO files) can be done by
+the same person for all languages, which saves overall time spent by
+translators to achieve this task: the node names and section titles
+are in English, so you can do. It is important to take advantage of
+this now, as it will be more complicated (but still possible) to do
+step 3) in all languages when documentation is compiled with
+texi2html and node names are directly translated in source files.
+
+
+MANAGING TRANSLATIONS WITH GIT
+
+This policy explains how to manage Git branches and commit
+translations to Git.
+
+* Translation changes matching master branch are preferably made on
+lilypond/translation branch; they may be pushed directly on master
+only if they do not break compilation of LilyPond and its
+documentation, and in this case they should be pushed to
+lilypond/translation too. Similarly, changes matching stable/X.Y are
+preferably made on lilypond/X.Ytranslation.
+
+* lilypond/translation Git branch may be merged into master only if
+LilyPond ('make all') and documentation ('make web') compile
+succesfully.
+
+* master Git branch may be merged into lilypond/translation whenever
+'make' and 'make web' are succesful (in order to ease documentation
+compilation by translators), or when significant changes had been made
+in documentation in English in master branch.
+
+* General maintenance may be done by anybody who knows what he does
+in documentation in all languages, without informing translators
+first. General maintenance include simple text substitutions
+(e.g. automated by sed), compilation fixes, updating Texinfo or
+lilypond-book commands, updating macros, updating ly code, fixing
+cross-references, and operations described in 'POLICY DURING GDP
+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
+repository; this is especially useful for translators who may have to
+deal with both lilypond/translation and a stable branch
+(e.g. stable/2.12 or lilypond/translation-2.12). To fetch and check
+out a new branch named BRANCH on git.sv.gnu.org, write the two
+following lines to a text file named .git/remotes/SHORTHAND --
+SHORTHAND is the name of the remote file, i.e. whatever easy-to-type
+name you would like to use when pulling or pushing BRANCH, and usually
+SHORTHAND is an abbreviation of BRANCH without slashes
+
+URL: git://git.sv.gnu.org/lilypond.git/
+Pull: BRANCH:refs/remotes/origin/BRANCH
+
+Then, run
+
+ git fetch SHORTHAND
+ git checkout -b BRANCH origin/BRANCH
+
+After this, you are able to pull BRANCH from git.sv.gnu.org with
+
+ git pull SHORTHAND
+
+You can check out another branch OTHER_BRANCH, i.e. check out
+OTHER_BRANCH to the working tree, with
+
+ git checkout OTHER_BRANCH
+
+E.g. lilypond/translation, which you still have in your local Git
+repository but is no longer checked out since you have created the new
+branch BRANCH.
+
+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 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
+of the "A:B" refspec in .git/remotes/SHORTHAND: as a matter of fact,
+when you pull using A:B refspec, Git fetch A on the server as B remote
+branch on your local repository, then tries to merge B into the
+currently checked out branch.
+
+To remember which branch is currently checked out, run 'git branch',
+which will list all branches and mark the currently checked out branch
+with a star, or 'git status'.
+
+
+* To merge branch FOO into branch BAR, i.e. to "add" all changes made
+in branch FOO to branch BAR, run
+
+ git checkout BAR
+ git merge FOO
+
+If any conflict happens, please carefully follow the instructions
+given by 'git merge' -- you usually must resolve conflicts with a text
+editor by merging pieces of files marked with "<<<" "===" and ">>>",
+removing these 3 kinds of conflict marks, then commit the result
+exactly like a usual commit.
+
+For example, as a translator, you will often want to merge master into
+lilypond/translation; on the other hand, the Translations meister
+wants to merge lilypond/translation into master whenever he has
+checked that lilypond/translation builds successfully.
+
+
+* If you play with several Git branches (e.g. master,
+lilypond/translation, stable/2.12), you may want to have one source
+and build tree for each branch; this is possible with subdirectories
+of your local Git repository, used as local cloned subrepositories.
+To create a local clone for the branch named BRANCH, run
+
+ git checkout BRANCH
+ git clone -l -s -n . SUBDIR
+ cd SUBDIR
+ git reset --hard
+
+Note that SUBDIR must be a directory name which does not already
+exist. In SUBDIR, you can use all Git commands to browse revisions
+history, commit and uncommit changes; to update the cloned
+subrepository with changes made on the main repository, cd into SUBDIR
+and run 'git pull'; to send changes made on the subrepository back to
+the main repository, run 'git push' from SUBDIR. Note that only one
+branch (the currently checked out branch) is created in the
+subrepository by default; it is possible to have several branches in a
+subrepository and do usual operations (checkout, merge, create,
+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:
+translation process. All are located in buildscripts/, except
+langdefs.py which is in python/
-* langdefs.py -- language definitions
+* 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
* html-gettext.py -- translate node names, section titles and cross
references in HTML files generated by makeinfo
-* add_html_footer.py (module called by www_post.py) -- add footer and
+* 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
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.
projects / lilypond.git / blobdiff