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
-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/master:remotemaster
- git checkout -b master remotemaster
+ mkdir lily ; cd lily ; git init-db ; mkdir .git/refs/remotes/origin
+
+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
* gettext
+WHICH DOCUMENTATION CAN BE TRANSLATED
+
+The makfiles and scripts infrastructure currently supports translation
+of the following documentation:
+
+ * documentation index (HTML)
+ * user manual and program usage -- Texinfo source, PDF and HTML
+output; Info output might be added if there is enough demand for it.
+
+
STARTING A TRANSLATION IN A NEW LANGUAGE
At top of the source directory, do
make ISOLANG=<MY-LANGUAGE> new-lang
-where <MY-LANGUAGE> is the ISO 639 language code
+where <MY-LANGUAGE> is the ISO 639 language code.
Add a language definition for your language in
buildscripts/langdefs.py.
See next section about what files to translate and the following
detailed instructions after the next section.
+
FILES TO BE TRANSLATED
All the following files are in Documentation/
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
-
--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
+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- 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/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 | sed 's@^@site/@')
-
-LANG=C wc --words $(grep ^2 TRANSLATION | cut -d ' ' -f 2 | sed 's@^@site/@')
+299 user/literature.itely
+960 user/scheme-tutorial.itely (needs to be revised first)
+1259 total
TRANSLATION DETAILED INSTRUCTIONS
Please follow all these instructions with care to ensure quality work.
-* USER MANUAL
+All files should be encoded in UTF-8.
+
+* 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
-@node @top @majorheading
+@node @majorheading
@chapter @unnumbered @appendix @chapheading
@section @unnumberedsec @appendixsec @heading
@subsection @unnumberedsubsec @appendixsubsec @subheading
@subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
@ref @rglos
+As a notable exception, the second argument 'Bar baz' of
+@ref{Foo,'Bar baz',,info-file} should be translated.
+
+@uref's names are to be translated.
In any section which looks like
the node names (nodeN) are NOT to be translated, whereas extra title
information (thingN) is.
-
Every node name or section title must from now on be translated
separately in a .po file (just as well as LilyPond output messages).
This .po file should be in Documentation/po.
-Make sure to keep *verbatim* copies of music snippets (in @lilypond blocs).
-@example blocs do not have to be verbatim copies, e.g. variable names,
+
+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
+user to understand the documentation; in this case, and only in this
+case, you may as an exception translate text in the music snippet, and
+then you must add a line immediately before the @lilypond block,
+beginning with
+
+@c KEEP LY
+
+Otherwise the music snippet would be reset to the same contents 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
+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.
Index entries (@cindex and so on) should be translated.
lilypond-devel@gnu.org.
+* REFERENCE NOTATION AND PROGRAM USAGE 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
+Unlike almost all HTML pages in this documentation, links in this page
+are not tweaked by add_html_footer.py, so links should be manually
+edited to link to existing translations.
CHECK STATE OF TRANSLATION
+First pull, then cd into Documentation (or at top of the source tree,
+replace 'make' with 'make -C Documentation') and run
+
+ 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, 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'
+
+
+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
+updated, run from Documentation
+
+ make ISOLANG=<MY_LANGUAGE> skeleton-update
+
+.po message catalogs in Documentation/po may be updated with (from
+Documentation or Documentation/po)
+
+ make po-update
+
+WARNING: if you run po-update and somebody else does the same and
+pushes before you push or send a patch to be applied, there will be a
+conflict when you pull. Therefore, it is better that only the
+Translation meister runs this command.
+
+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):
+
+ make ISOLANG=<MY_LANGUAGE> snippet-update
+
+This script overwrites music snippets in <MY_LANGUAGE>/user/every.itely
+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.
+
+Finally, a command runs the three update processes above for all
+enabled languages (from Documentation):
+
+ make all-translations-update
+
+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
-*** This section is a draft and should be overhauled ***
-- J. Mandereau
-
-When starting a translation, texi-langutils.py quickly parses
-lilypond.tely and the included .itely's, and generates a skeleton with
-node and sectionning commands. When translating a .itely file, the
-skeleton file is replaced with the real translation, in exception of
-the the node, sectioning and glossary reference commands, which
-remains in English. All this ensures easy navigation between nodes in
-different languages in HTML docs, i.e.: there is automatic language
-selection on lilypond.org, all sections and cross-references are
-always available, at least in English (for example, see the "Other
-languages: xxx" menu at bottom of tutorial pages). From the user's
-point of view, docs in his native language with node and sections in
-English are painful, so texi-langutils generates a .po of node and
-section names; this .po file is used to translate the section titles
-in the HTML generated docs.
+A number of Python scripts handle a part of the documentation
+translation process:
+
+* langdefs.py -- language definitions
+* 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
+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
projects / lilypond.git / blobdiff