SOURCES
-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
+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
- git fetch git://git.sv.gnu.org/lilypond.git/ refs/heads/lilypond/translation:lilypond/translation
- git checkout -b mytranslations lilypond/translation
+ 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.
+Word counts (excluding lilypond snippets) are given for each file.
--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
+-1- Documentation index and Tutorial
+396 user/lilypond-learning.tely
+5593 user/tutorial.itely
+23 user/dedication.itely
+216 index.html.in
+2022 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
+8250 total
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
+-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
-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
+8626 user/fundamental.itely -- Fundamental concepts
+12134 user/tweaks.itely -- Tweaking output
+2985 user/working.itely -- Working on LilyPond files
+483 user/templates.itely -- Templates
+24228 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
+539 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
+702 user/piano.itely
+481 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
+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
+250 user/cheatsheet.itely -- Cheat sheet
+53639 total
+
+-5- Application usage
+2917 user/lilypond-book.itely -- LilyPond-book
+975 user/converters.itely -- Converting from other formats
+3892 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
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
+string 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! For instance,
+input/texidocs/FILENAME.texidoc may contain
+
+texidoces = "
+Spanish translation blah
+"
+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
- python buildscripts/check_translation.py Documentation/<MY-LANGUAGE>/user/foo.itely
+ make ISOLANG=<MY_LANGUAGE> check-translation | grep 'diff --git'
+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.
+
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
This command is mainly intended to be used by the Translation meister.
+MISCELLANEOUS: 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 ouy 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 deafult; it is possible to have several branches in a
+subrepository and do usual operations (checkout, merge, create,
+delete...) on these branches, but this is more difficult to manage
+them and sync them with the main repository, so this possibility is
+not detailed here.
+
+
TECHNICAL BACKGROUND
A number of Python scripts handle a part of the 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