+++ /dev/null
-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
-
-
-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
-
-The reader is supposed to be familiar with Git, for example by
-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
-
-Working on LilyPond documentation translations requires:
-
- * python
- * make
- * 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
-
- ./autogen.sh
-
-or (if you want to install your self-compiled LilyPond locally):
-
- ./autogen.sh --prefix=$HOME
-
-If you want to compile LilyPond -- which is almost required to build
-the docs, but is not required to do translation only -- fix all
-dependencies and rerun ./configure (with the same options as for
-autogen).
-
-Cd into Documentation and run:
-
- make ISOLANG=<MY-LANGUAGE> new-lang
-
-where <MY-LANGUAGE> is the ISO 639 language code.
-
-Add a language definition for your language in
-python/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/
-Translation of Documentation/foo/bar should be
-Documentation/<LANG>/foo/bar.
-Unmentioned files should not be translated.
-
-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 and Tutorial
-429 user/lilypond-learning.tely
-6365 user/tutorial.itely
-23 user/dedication.itely
-432 user/macros.itexi
-171 index.html.in
-6346 po/lilypond-doc.pot (translate to po/<MY_LANGUAGE>.po)
---- ../lilypond-texi2html.init (section TRANSLATIONS)
-13766 total
-
--2- Introduction and beginning of Application Usage
-411 user/preface.itely
-3855 user/introduction.itely
-407 user/lilypond-program.tely
-1921 user/install.itely (partial translation)
-1149 user/setup.itely
-2827 user/running.itely
-10570 total
-
--3- Learning manual
-10318 user/fundamental.itely -- Fundamental concepts
-14775 user/tweaks.itely -- Tweaking output
-3144 user/working.itely -- Working on LilyPond files
-483 user/templates.itely -- Templates
-28720 total
-
--4- Notation reference
-695 user/lilypond.tely
-91 user/notation.itely -- Musical notation
-3123 user/pitches.itely
-5197 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
-810 user/percussion.itely
-826 user/guitar.itely
-66 user/strings.itely
-242 user/bagpipes.itely
-4487 user/ancient.itely
-5873 user/input.itely -- Input syntax
-2164 user/non-music.itely -- Non-musical notation
-8505 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
-63062 total
-
--5- Application usage
-3248 user/lilypond-book.itely -- LilyPond-book
-1171 user/converters.itely -- Converting from other formats
-4419 total
-
--6- Appendices whose translation is optional
-310 user/literature.itely
-960 user/scheme-tutorial.itely (needs to be revised first)
-1270 total
-
-
-TRANSLATION DETAILED INSTRUCTIONS
-
-Please follow all these instructions with care to ensure quality work.
-
-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 @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
-
-@menu
-* node1:: thing1
-* node2:: thing2
-...
-@end menu
-
-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.
-
-
-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
-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 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.
-
-Index entries (@cindex and so on) should be translated.
-
-Carefully apply every rule exposed in Documentation/README.txt. If
-one of these rules conflicts with a rule specific to your language,
-please ask the Translation meister and/or the Documentation Editor on
-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'
-
-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
-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
-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 that 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. 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):
-
- make all-translations-update
-
-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 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
-
-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.
-All scripts used to maintain the translations
-are located in scripts/auxiliar/:
-
-* 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
-* 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
-
-Python modules used by scripts in scripts/auxiliar/ or scripts/build/ (but
-not by installed Python scripts) are located in python/auxiliar/:
-* 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
@end ifhtml
+@iftex
+@exampleindent 0
@finalout
@titlepage
For LilyPond version
@end titlepage
+@end iftex
@copying
Copyright @copyright{} 1999--2008 by the authors
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@c This file is part of file doc-work.itexi
+@c Word counts are updated automatically by translations-status.py
+
+Translation of @file{Documentation/foo/bar} should be
+@file{Documentation/@var{LANG}/foo/bar}. Unmentioned files should not
+be translated.
+
+Priorities:
+@itemize
+@item 1. delivery,
+@item 2. 3. 4. 5. later,
+@item 6. optional.
+@end itemize
+
+Files marked with priority 3, 4 or 5 may be submitted individually.
+Word counts (excluding LilyPond snippets) are given for each file.
+
+@example
+-1- Documentation index and Tutorial
+429 user/lilypond-learning.tely
+6365 user/tutorial.itely
+23 user/dedication.itely
+423 user/macros.itexi
+171 index.html.in
+6346 po/lilypond-doc.pot (translate to po/@var{MY_LANGUAGE}.po)
+--- ../lilypond-texi2html.init (section TRANSLATIONS)
+13757 total
+
+-2- Introduction and beginning of Application Usage
+411 user/preface.itely
+3855 user/introduction.itely
+407 user/lilypond-program.tely
+1928 user/install.itely (partial translation)
+1149 user/setup.itely
+2827 user/running.itely
+10577 total
+
+-3- Learning manual
+10318 user/fundamental.itely -- Fundamental concepts
+14775 user/tweaks.itely -- Tweaking output
+3007 user/working.itely -- Working on LilyPond files
+483 user/templates.itely -- Templates
+28583 total
+
+-4- Notation reference
+695 user/lilypond.tely
+91 user/notation.itely -- Musical notation
+3123 user/pitches.itely
+5236 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
+810 user/percussion.itely
+826 user/guitar.itely
+66 user/strings.itely
+242 user/bagpipes.itely
+4487 user/ancient.itely
+5873 user/input.itely -- Input syntax
+2164 user/non-music.itely -- Non-musical notation
+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
+63047 total
+
+-5- Application usage
+3248 user/lilypond-book.itely -- LilyPond-book
+1171 user/converters.itely -- Converting from other formats
+4419 total
+
+-6- Appendices whose translation is optional
+310 user/literature.itely
+960 user/scheme-tutorial.itely (needs to be revised first)
+1270 total
+@end example
-@c -*- coding: us-ascii; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Documentation work
@chapter Documentation work
@menu
* Introduction to documentation work::
-* Texinfo crash course::
+* Texinfo introduction and usage policy::
* Documentation policy::
* Tips for writing docs::
* Updating docs with convert-ly::
-@node Texinfo crash course
-@section Texinfo crash course
+@node Texinfo introduction and usage policy
+@section Texinfo introduction and usage policy
+
+@menu
+* Texinfo introduction::
+* Sectioning commands::
+* LilyPond formatting::
+* Text formatting::
+* Syntax survey::
+* Other text concerns::
+@end menu
+
+
+@node Texinfo introduction
+@subsection Texinfo introduction
+
+The language is called Texinfo; you can see its manual here:
-The language is called texinfo; you can see its manual here:
@uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
However, you don't need to read those docs. The most important
@node Updating docs with convert-ly
-@section Updating doc with convert-ly
+@section Updating doc with @command{convert-ly}
cd into Documentation and run
@end example
@noindent
-(This also updates translated docs.)
-
+This also updates translated documentation.
@node Translating the documentation
@section Translating the documentation
+@menu
+* Getting started with documentation translation::
+* Documentation translation details::
+* Documentation translation maintenance::
+* Translations management policies::
+* Technical background::
+@end menu
+
+@node Getting started with documentation translation
+@subsection Getting started with documentation translation
+
+First, get the sources from the Git repository, see @ref{Documentation
+translations source code}.
+
+@menu
+* Translation requirements::
+* Which documentation can be translated::
+* Starting translation in a new language::
+@end menu
+
+@node Translation requirements
+@unnumberedsubsubsec Translation requirements
+
+Working on LilyPond documentation translations requires the following
+pieces of software, in order to make use of dedicated helper tools:
+
+@itemize
+@item Python 2.4 or higher,
+@item GNU Make,
+@item Gettext.
+@end itemize
+
+It is not required to build LilyPond and the documentation to
+translate the documentation. However, if you have enough time and
+motivation and a suitable system, it can be very useful to build at
+least the documentation so that you can check the output yourself and
+more quickly; if you are interested, see @ref{Compiling from source}.
+
+@menu
+@end menu
+
+@node Which documentation can be translated
+@unnumberedsubsubsec Which documentation can be translated
+
+The makefiles and scripts infrastructure currently supports translation
+of the following documentation:
+
+@itemize
+@item documentation index (HTML);
+@item user manual and program usage -- Texinfo source, PDF and HTML
+output; Info output might be added if there is enough demand for it;
+@item the News document.
+@end itemize
+
+The following pieces of documentation should be added soon, by
+descending order of priority:
+
+@itemize
+@item automatically generated documentation: markup commands,
+predefined music functions;
+@item the Snippets List;
+@item the examples page;
+@item the Internals Reference.
+@end itemize
+
+
+@node Starting translation in a new language
+@unnumberedsubsubsec Starting translation in a new language
+
+At top of the source directory, do
+
+@example
+./autogen.sh
+@end example
+
+@noindent
+or (if you want to install your self-compiled LilyPond locally)
+
+@example
+./autogen.sh --prefix=$HOME
+@end example
+
+@noindent
+If you want to compile LilyPond -- which is almost required to build
+the documentation, but is not required to do translation only -- fix
+all dependencies and rerun @command{./configure} (with the same
+options as for @command{autogen.sh}).
+
+Then @command{cd} into @file{Documentation} and run
+
+@example
+make ISOLANG=@var{MY-LANGUAGE} new-lang
+@end example
+
+@noindent
+where @var{MY-LANGUAGE} is the ISO 639 language code.
+
+Finally, add a language definition for your language in
+@file{python/langdefs.py}.
+
+Before starting the real translation work, it is recommended to commit
+changes you made so far to Git, so e.g. you are able to get back to
+this state of the sources easily if needed; see @ref{Sharing your
+changes}.
+
+
+@node Documentation translation details
+@subsection Documentation translation details
+
+Please follow all the instructions with care to ensure quality work.
+
+All files should be encoded in UTF-8.
+
+@menu
+* Files to be translated::
+* Translating the Learning Manual and other Texinfo documentation::
+* Translating the Notation Reference and Application Usage::
+* Translating the Documentation index index.html.in::
+@end menu
+
+@node Files to be translated
+@unnumberedsubsubsec Files to be translated
+
+@include doc-translation-list.itexi
+
+@node Translating the Learning Manual and other Texinfo documentation
+@unnumberedsubsubsec Translating the 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
+
+@example
+@@node @@majorheading
+@@chapter @@unnumbered @@appendix @@chapheading
+@@section @@unnumberedsec @@appendixsec @@heading
+@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
+@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
+@@ref @@rglos
+@end example
+
+As a notable exception, the second argument @var{Bar baz} of
+@code{@@ref@{@var{Foo},@var{Bar baz},,@var{info-file}@}} should be
+translated.
+
+@code{@@uref}'s names are to be translated.
+
+In any section which looks like
+
+@example
+@@menu
+* @var{node1}:: @var{thing1}
+* @var{node2}:: @var{thing2}
+...
+@@end menu
+@end example
+
+@noindent
+the node names @var{nodeN} are @emph{not} to be translated, whereas
+extra title information @var{thingN} is.
+
+Every node name or section title must from now on be translated
+separately in a @file{.po} file (just as well as LilyPond output
+messages) in @file{Documentation/po}. The Gettext domain is named
+@code{lilypond-doc}, and unlike @code{lilypond} domain it is not
+managed through the Free Translation Project.
+
+
+Take care of using typographic rules for your language, especially in
+@file{user/macros.itexi}.
+
+
+Please keep verbatim copies of music snippets (in @code{@@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
+@code{@@lilypond} block, starting with
+
+@example
+@@c KEEP LY
+@end example
+
+@noindent
+Otherwise the music snippet would be reset to the same content as the
+English version at next @command{make snippet-update} run -- see
+@ref{Updating documentation translation}.
+
+When you encounter
+
+@example
+@@lilypondfile[<number of fragment options>,texidoc]@{@var{filename.ly}@}
+@end example
+
+@noindent
+in the source, open @file{input/lsr/@var{filename}.ly}, translate the
+@code{texidoc} header field it contains, enclose it with
+@code{texidoc@var{MY-LANGUAGE} = "} and @code{"}, and write it into
+@file{input/texidocs/@var{filename}.texidoc} -- please keep possibly
+existing translations in other languages! Additionnally, you may
+translate the snippet's title in @code{doctitle} header field, in case
+@code{doctitle} is a fragment option used in @code{@@lilypondfile};
+you can do this exactly the same way as @code{texidoc}. For instance,
+@file{input/texidocs/@var{filename}.texidoc} may contain
+
+@example
+doctitlees = "Spanish title baz"
+texidoces = "
+Spanish translation blah
+"
+doctitlede = "German title bar"
+texidocde = "German translation foo
+"
+@end example
+
+@code{@@example} blocs need not be verbatim copies, e.g. variable
+names, file names and comments should be translated.
+
+Index entries (@code{@@cindex} and so on) should be translated.
+
+Finally, please carefully apply every rule exposed in @ref{Texinfo
+introduction and usage policy}, and @ref{Documentation policy}. If
+one of these rules conflicts with a rule specific to your language,
+please ask the Translation meister and/or the Documentation Editors on
+@email{lilypond-devel@@gnu.org}.
+
+
+@node Translating the Notation Reference and Application Usage
+@unnumberedsubsubsec Translating the Notation Reference and Application Usage
+
+Copy @file{user/lilypond.tely} (or @file{user/lilypond-program.tely},
+respectively) into @file{@var{MY-LANGUAGE}/user}, then translate this
+file and run @code{skeleton-update} -- see @ref{Updating documentation
+translation}. Your are now ready to translate the Notation Reference
+(Application Usage, respectively) exactly like the Learning Manual.
+
+
+@node Translating the Documentation index index.html.in
+@unnumberedsubsubsec Translating the Documentation index @file{index.html.in}
+
+Unlike almost all HTML pages in this documentation, links in this page
+are not tweaked by @file{postprocess_html.py}, so links should be
+manually edited to link to existing translations.
+
+
+@node Documentation translation maintenance
+@subsection Documentation translation maintenance
+
+Several tools have been developed to make translations maintenance
+easier. These helper scripts make use of the power of Git, the
+version control system used for LilyPond development.
+
+@menu
+* Check state of translation::
+* Updating documentation translation::
+@end menu
+
+@node Check state of translation
+@unnumberedsubsubsec Check state of translation
+
+First pull from Git, then cd into @file{Documentation/} (or at top of
+the source tree, replace @command{make} with @command{make -C
+Documentation}) and run
+@example
+make ISOLANG=@var{MY_LANGUAGE} check-translation
+@end example
+
+@noindent
+This presents a diff of the original files since the most recent
+revision of the translation. To check a single file, cd into
+@file{Documentation/} and run
+
+@example
+make CHECKED_FILES=@var{MY_LANGUAGE/user/foo.itely} check-translation
+@end example
+
+To see only which files need to be updated, do
+
+@example
+make ISOLANG=@var{MY_LANGUAGE} check-translation | grep 'diff --git'
+@end example
+
+To avoid printing terminal colors control characters, which is often
+desirable when you redirect output to a file, run
+
+@example
+make ISOLANG=@var{MY_LANGUAGE} NO_COLOR=1 check-translation
+@end example
+
+Global state of the translation is recorded in
+@file{Documentation/translations.html.in}, which is used to generate
+Translations status page. To update that page, do from
+@file{Documentation/}
+
+@example
+make translation-status
+@end example
+
+This will also leave @file{out/translations-status.txt}, which contains
+up-to-dateness percentages for each translated file, and update word
+counts of documentation files in this Guide.
+
+@seealso
+
+@ref{Maintaining without updating translations}.
+
+
+@node Updating documentation translation
+@unnumberedsubsubsec Updating documentation translation
+
+Instead of running @code{check-translation}, you may want to run
+@code{update-translation}, which will run your favorite text editor to
+update files. First, make sure environment variable @code{EDITOR} is
+set to a text editor command, then run from @file{Documentation/}
+
+@example
+make ISOLANG=@var{MY_LANGUAGE} update-translation
+@end example
+
+or to update a single file
+
+@example
+make CHECKED_FILES=@var{MY_LANGUAGE/user/foo.itely} update-translation
+@end example
+
+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. @file{.itely} files not yet translated,
+containing only the Texinfo structure can be updated automatically:
+whenever @command{make check-translation} shows that such files should
+be updated, run from @file{Documentation/}
+
+@example
+make ISOLANG=@var{MY_LANGUAGE} skeleton-update
+@end example
+
+@file{.po} message catalogs in @file{Documentation/po/} may be updated
+by issuing from @file{Documentation/} or @file{Documentation/po/}
+
+@example
+make po-update
+@end example
+
+@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 that can do this odd job for you (run from
+@file{Documentation/}):
+
+@example
+make ISOLANG=@var{MY_LANGUAGE} snippet-update
+@end example
+
+This script overwrites music snippets in
+@file{@var{MY_LANGUAGE/user/every.itely}} with music snippets from
+@file{@var{user/every.itely}}. It ignores skeleton files, and keeps
+intact music snippets preceded with a line starting with @code{@@c
+KEEP LY}; it reports an error for each @file{.itely} that has not the
+same 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 @command{git diff} before committing; if you
+don't do so, some @code{@@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 @file{Documentation/}):
+
+@example
+make all-translations-update
+@end example
+
+Use this command with caution, and keep in mind it will not be really
+useful until translations are stabilized after the end of GDP.
+
+@seealso
+
+@ref{Maintaining without updating translations}.
+
+
+@node Translations management policies
+@subsection Translations management policies
+
+These policies show the general intent of how the translations should
+be managed, they aim at helping translators, developers and
+coordinators work efficiently.
+
+@menu
+* Maintaining without updating translations::
+* Managing documentation translation with Git::
+@end menu
+
+@node Maintaining without updating translations
+@unnumberedsubsubsec Maintaining without updating translations
+
+Keeping translations up to date under heavy changes in the
+documentation in English may be almost impossible, especially as
+during the former Grand Documentation Project (GDP) or the Grand
+Organization Project (GOP) when a lot of contributors brings changes.
+In addition, transloators may be (and that) involved in these porjects too.
+
+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 rationale below the tasks
+list motivates this plan.
+
+The following tasks are listed in decreasing priority order.
+
+@enumerate
+@item 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.
+
+@item Update @file{*.tely} files completely with
+@command{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 @ref{Check state of translation}.
+
+@item In @file{.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 @code{@@node} and
+@code{@@section}-command from English docs, and add the marker for
+untranslated status @code{@@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 @code{@@c obsolete} just before the node.
+
+Emacs with Texinfo mode makes this step easier:
+
+@itemize
+@item without Emacs AucTeX installed, @key{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 @key{C-x 1}
+and @key{C-x 2}), press @key{C-c C-s} to show structure of one file
+(e.g. the translated file), copy *Occur* contents into *Scratch*, then
+press @key{C-c C-s} for the other file.
+
+If you happen to have installed AucTeX, you can either call the macro
+by doing @key{M-x texinfo-show-structure} or create a key binding in your
+@file{~/.emacs}, by adding the four following lines:
+
+@example
+(add-hook 'Texinfo-mode-hook
+ '(lambda ()
+ (define-key Texinfo-mode-map "\C-cs"
+ 'texinfo-show-structure)))
+@end example
+
+@noindent
+and then obtain the structure in the *Occur* buffer with @key{C-c s}.
+
+@item Do not bother updating @code{@@menu}s when all menu entries are in the same
+file, just do @key{C-c C-u C-a} ("update all menus") when you have
+updated all the rest of the file.
+
+@item Moving to next or previous node using incremental search: press
+@key{C-s} and type @code{node} (or @key{C-s @@node} if the text
+contains the word @q{node}) then press @key{C-s} to move to next node
+or @key{C-r} to move to previous node. Similar operation can be used
+to move to the next/previous section. Note that every cursor move
+exits incremental search, and hitting @key{C-s} twice starts
+incremental search with the text entered in previous incremental
+search.
+
+@item Moving a whole node (or even a sequence of nodes): jump to beginning
+of the node (quit incremental search by pressing an arrow), press
+@key{C-SPACE}, press @key{C-s node} and repeat @key{C-s} until you
+have selected enough text, cut it with @key{C-w} or @key{C-x}, jump to
+the right place (moving between nodes with the previous hint is often
+useful) and paste with @key{C-y} or @key{C-v}.
+@end itemize
+
+@item Update sections finished in the English documentation; check
+sections status at
+@uref{http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination}.
+
+@item Update documentation PO. It is recommended not to update
+strings which come from documentation that is currently deeply revised
+in English, to avoid doing the work more than once.
+
+@item Fix broken cross-references by running (from @file{Documentation/})
+
+@example
+make ISOLANG=@var{YOUR-LANGUAGE} fix-xrefs
+@end example
+
+@noindent
+This step requires a sucessful documentation build (with @command{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.
+@end enumerate
+
+@subsubheading 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.
+
+@itemize
+@item 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.
+
+@item This just makes translated documentation take advantage of the new
+organization, which is better than the old one.
+
+@item 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.
+
+@item Each maintenance task except @q{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
+@command{texi2html} and node names are directly translated in source
+files.
+@end itemize
+
+
+@node Managing documentation translation with Git
+@unnumberedsubsubsec Managing documentation translation with Git
+
+This policy explains how to manage Git branches and commit
+translations to Git.
+
+@itemize
+@item Translation changes matching master branch are preferably made on
+@code{lilypond/translation} branch; they may be pushed directly to
+@code{master} only if they do not break compilation of LilyPond and
+its documentation, and in this case they should be pushed to
+@code{lilypond/translation} too. Similarly, changes matching
+@code{stable/X.Y} are preferably made on
+@code{lilypond/X.Ytranslation}.
+
+@item @code{lilypond/translation} Git branch may be merged into master only if
+LilyPond (@command{make all}) and documentation (@command{make web}) compile
+succesfully.
+
+@item @code{master} Git branch may be merged into
+@code{lilypond/translation} whenever @command{make} and @command{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.
+
+@item 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 @ref{Maintaining
+without updating translations}.
+@end itemize
+
+
+@node Technical background
+@subsection Technical background
+
+A number of Python scripts handle a part of the documentation
+translation process. All scripts used to maintain the translations
+are located in @file{scripts/auxiliar/}.
+
+@itemize
+@item @file{check_translation.py} -- show diff to update a translation,
+@item @file{texi-langutils.py} -- quickly and dirtily parse Texinfo files to
+make message catalogs and Texinfo skeleton files,
+@item @file{texi-skeleton-update.py} -- update Texinfo skeleton files,
+@item @file{update-snippets.py} -- synchronize ly snippets with those
+from English docs,
+@item @file{translations-status.py} -- update translations status pages and word
+counts in the file you are reading,
+@item @file{tely-gettext.py} -- gettext node names, section titles and references
+in the sources; WARNING only use this script once for each file, when support for
+"makeinfo --html" has been dropped.
+@end itemize
+
+Other scripts are used in the build process, in @file{scripts/build/}:
+
+@itemize
+@item @file{html-gettext.py} -- translate node names, section titles and cross
+references in HTML files generated by @command{makeinfo},
+@item @file{texi-gettext.py} -- gettext node names, section titles and references
+before calling @command{texi2pdf},
+@item @file{mass-link.py} -- link or symlink files between English documentation
+and documentation in other languages.
+@end itemize
+
+Python modules used by scripts in @file{scripts/auxiliar/} or @file{scripts/build/} (but
+not by installed Python scripts) are located in @file{python/auxiliar/}:
+@itemize
+@item @file{manuals_definitions.py} -- define manual names and name of
+cross-reference Texinfo macros,
+@item @file{buildlib.py} -- common functions (read piped output
+of a shell command, use Git),
+@item @file{postprocess_html.py} (module imported by @file{www_post.py}) -- add footer and
+tweak links in HTML pages.
+@end itemize
+
+And finally
+@itemize
+@item @file{python/langdefs.py} -- language definitions module
+@end itemize
@node Starting with git
@chapter Starting with git
+To complete or present in another form the introduction to Git usage
+in this chapter, it may be a good idea to look for Git documentation
+at @uref{http://git-scm.com/documentation},
+
@menu
* Getting the source code::
* Updating the source code::
+* Working with several Git branches::
* Sharing your changes::
* Other interesting Git commands::
* Git on Windows::
@node Git introduction
@subsection Git introduction
-The source code is kept in a git respository. This allows us to
+The source code is kept in a Git respository. This allows us to
track changes to files, and for multiple people to work on the
-same set of files (generally) without any problems.
+same set of files efficiently.
@warning{These instructions assume that you are using the
-command-line version of git 1.5 or higher. Windows users should
+command-line version of Git 1.5 or higher. Windows users should
skip to @ref{Git on Windows}.}
To get the main source code and documentation,
-FIXME: test this!!!
-
-@example
+@c WARNING: when updating the commands below, please
+@c update the other flavors in the two next nodes
+@c and in Introduction to Git concepts
+@smallexample
mkdir lilypond; cd lilypond
git init-db
git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
git checkout -b master origin/master
-@end example
+@end smallexample
@node Website source code
To get the website (including translations),
-FIXME: test this!!!
-
-@example
+@smallexample
mkdir lilypond-web ; cd lilypond-web
git init-db
git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
git checkout -b web origin/web
-@end example
+@end smallexample
@node Documentation translations source code
To translate the documentation (@emph{not} the website),
-FIXME: change!!!
-
-@example
-mkdir lilypond-translate; cd lilypond-translate
+@smallexample
+mkdir lilypond-translation; cd lilypond-translation
git init-db
-git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
-git checkout -b web origin/web
-@end example
+git remote add -f -t lilypond/translation -m lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
+git checkout -b lilypond/translation origin/lilypond/translation
+@end smallexample
@node Other branches
ssh://git.sv.gnu.org/srv/git/lilypond.git
@end example
-@warning{The @code{git://} and @code{ssh://} URLs are intended for
-advanced git users.}
+Using HTTP protocol is slowest, so it is not recommended unless both
+SSH and Git protocols fail, which happens e.g. if you connect to
+internet through a router that filters out Git and/or SSH connections.
+
@node Git user configuration
@subsection Git user configuration
To configure git to automatically use your name and email address
-for patches,
+for commits and patches,
@example
git config --global user.name "MYNAME"
* Importance of updating::
* Update command::
* Resolving conflicts::
-* Technical notes::
+* Introduction to Git concepts::
@end menu
@node Importance of updating
@subsection Importance of updating
-In a large project like LilyPond, contributors sometimes edit the
-same file at the same time. As long as everybody updates their
-version of the file with the most recent changes (@qq{pull}ing),
-there are generally no problems with this multiple-person editing.
-However, serious problems can arise if you do not pull before
-attempting commit.
+In a large project like LilyPond, contributors sometimes edit the same
+file at the same time. As long as everybody updates their version of
+the file with the most recent changes (@emph{pulling}), there are
+generally no problems with this multiple-person editing. However,
+boring problems can arise if you do not pull before attempting commit,
+e.g. you may encounter a conflict; in this case, see @ref{Resolving
+conflicts}.
@node Update command
together. When this happens, you must manually merge the two
versions.
+If you need some documentation to understand and resolve conflicts,
+see paragraphs @emph{How conflicts are presented} and @emph{How to
+resolve conflicts} in @command{git merge} man page.
+
+
+@node Introduction to Git concepts
+@subsection Introduction to Git concepts
+
+A bit of Git vocabulary will be explained below. The following is
+just introduction material; for better understanding of Git concepts,
+you are invited to read further documentation, especially Git
+Community Book at @uref{http://book.git-scm.com/}.
+
+The @code{git pull origin} command above is just a shortcut for this
+command:
+
@example
-TODO
+git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
@end example
+@noindent
+where @code{@var{branch}} is typically @code{master}, @code{web} or
+@code{lilypond/translation}; if you do not know or remember, see
+@ref{Getting the source code} to remember which commands you issued or
+which source code you wanted to get.
+
+A @emph{commit} is a set of changes made to the sources; it also
+includes the committish of the parent commit, the name and e-mail of
+the @emph{author} (the person who wrote the changes), the name and
+e-mail of the @emph{committer} (the person who brings these changes
+into the Git repository), and a commit message.
+
+A @emph{committish} is the SHA1 checksum of a commit, a number made of
+40 hexadecimal digits, which acts as the internal unique identifier
+for this commit. To refer to a particular revision, don't use vague
+references like the (approximative) date, simply copy and paste the
+committish.
+
+A @emph{branch} is nothing more than a pointer to a particular commit,
+which is called the @emph{head} of the branch; when referring to a
+branch, one often acutally thinks about its head and the ancestor
+commits of the head.
+
+Now we will explain the two last commands you used to get the source
+code from Git -- see @ref{Getting the source code}.
-@node Technical notes
-@subsection Technical notes
+@example
+git remote add -f -t @var{branch} -m @var{branch} origin git://git.sv.gnu.org/lilypond.git/
+git checkout -b @var{branch} origin/@var{branch}
+@end example
+
+The @command{git remote} has created a branch called
+@code{origin/@var{branch}} in your local Git repository. As this
+branch is a copy of the remote branch web from git.sv.gnu.org LilyPond
+repository, it is called a @emph{remote branch}, and is meant to track
+the changes on the branch from git.sv.gnu.org: it will be updated
+every time you run @command{git pull origin} or @command{git fetch
+origin}.
+
+The @command{git checkout} command has created a branch named
+@code{@var{branch}}. At the beginning, this branch is identical to
+@code{origin/@var{branch}}, but it will differ as soon as you make
+changes, e.g. adding newly translated pages or editing some
+documentation or code source file. Whenever you pull, you merge the
+changes from @code{origin/@var{branch}} and @code{@var{branch}} since
+the last pulling. If you do not have push (i.e. @qq{write}) access on
+git.sv.gnu.org, your @code{@var{branch}} will always differ from
+@code{origin/@var{branch}}. In this case, remember that other people
+working like you with the remote branch @code{@var{branch}} of
+git://git.sv.gnu.org/lilypond.git/ (called @code{origin/@var{branch}}
+on your local repository) know nothing about your own
+@code{@var{branch}}: this means that whenever you use a committish or
+make a patch, others expect you to take the latest commit of
+@code{origin/@var{branch}} as a reference.
+
+Finally, please remember to read the man page of every Git command you
+will find in this manual in case you want to discover alternate
+methods or just understand how it works.
+
+
+@node Working with several Git branches
+@section Working 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 @code{lilypond/translation} and a stable branch,
+e.g. @code{stable/2.12}.
+
+Some Git commands are introduced first, then a workflow with several
+Git branches of LilyPond source code is presented.
+
+@menu
+* Git commands for managing several branches::
+* Working on LilyPond sources with several branches::
+@end menu
+
+@node Git commands for managing several branches
+@subsection Git commands for managing several branches
-TODO: I'm not going to bother with this section. -gp
+@subsubheading Listing branches and remotes
-Let's explain a bit of Git vocabulary. The @code{git pull origin}
-command is just a shortcut for this command:
+You can get the exact path or URL of all remotes with
+running
@example
-git pull git://git.sv.gnu.org/lilypond.git/ MY-BRANCH:origin/MY-BRANCH
+git remote -v
@end example
-A commit is a set of changes made to the sources; it also includes
-the committish of the parent commit, the name and e-mail of the
-author (the person who wrote the changes), the name and e-mail of
-the committer (the person who brings these changes into the git
-repository), and a commit message.
+To list Git branches on your local repositories, run
-A committish is the SHA1 checksum of a commit, a number made of 40
-hexadecimal digits, which acts as the internal unique identifier
-for this commit. To refer to a particular revision, don't use
-vague references like the (approximative) date, simply
-copy'n'paste the committish.
+@example
+git branch # list local branches only
+git branch -r # list remote branches
+git branch -a # list all branches
+@end example
-A branch is a tree (in the mathematical or computer science sense)
-of commits, and the topmost commit of this branch is called a
-head.
-The "git fetch" command above has created a branch called
-@code{origin/web} in your local Git repository. As this branch is
-a copy of the remote branch web from git.sv.gnu.org LilyPond
-repository, it is called a `remote branch', and is meant to track
-the changes on the branch from git.sv.gnu.org: it will be updated
-every time you run 'git pull' or 'git fetch' with this branch
-reference as argument, e.g. by using .git/remotes/web remote file
-when running 'git fetch web'.
-
-The 'git checkout' command above has created a branch named 'web'. At
-the beginning, this branch is identical to 'origin/web', but it will
-differ as soon as you make changes, e.g. adding newly translated
-pages. Whenever you pull, you merge the changes from origin/web and
-your web branch since the last pulling. If you do not have push
-(i.e. "write") access on git.sv.gnu.org, your web branch will always
-differ from origin/web. In this case, remember that other people
-working like you on the remote web branch of
-git://git.sv.gnu.org/lilypond.git/ know nothing about your own web
-branch: this means that whenever you use a committish or make a patch,
-others expect you to take the lastest commit of origin/web branch as a
-reference.
-
-This README tries to explain most of Git commands needed for
-translating the web site. However, you are invited to read
-further documentation to make git more familiar to you; for
-instance, take a look at @uref{http://git.or.cz/gitwiki/},
-especially GitDocumentation and GitGlossary; a good alternative to
-reading the wiki is reading the first two chapters of Git User's
-Manual at
-@uref{http://www.kernel.org/pub/software/scm/git/docs/user-manual.html}
+@subsubheading Checking out branches
+
+To know the currently checked out branch, i.e. the branch whose source
+files are present in your working tree, read the first line of the
+output of
+
+@example
+git status
+@end example
+
+@noindent
+The currently checked out branch is also marked with an asterisk in
+the output of @command{git branch}.
+
+You can check out another branch @code{@var{other_branch}}, i.e. check
+out @code{@var{other_branch}} to the working tree, by running
+
+@example
+git checkout @var{other_branch}
+@end example
+
+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 @command{git status} to check
+this kind of issue before checking out another branch.
+
+
+@subsubheading Merging branches
+
+To merge branch @code{@var{foo}} into branch @code{@var{bar}}, i.e. to
+@qq{add} all changes made in branch @code{@var{foo}} to branch
+@code{@var{bar}}, run
+
+@example
+git checkout @var{bar}
+git merge @var{foo}
+@end example
+
+If any conflict happens, see @ref{Resolving conflicts}.
+
+There are common usage cases for merging: as a translator, you will
+often want to merge @code{master} into @code{lilypond/translation}; on
+the other hand, the Translations meister wants to merge
+@code{lilypond/translation} into @code{master} whenever he has checked
+that @code{lilypond/translation} builds successfully.
+@node Working on LilyPond sources with several branches
+@subsection Working on LilyPond sources with several branches
+
+@subsubheading Fetching new branches from git.sv.gnu.org
+
+To fetch and check out a new branch named @code{@var{branch}} on
+git.sv.gnu.org, run from top of the Git repository
+
+@example
+git config --add remote.origin.fetch +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
+git checkout --track -b @var{branch} origin/@var{branch}
+@end example
+
+After this, you can pull @code{@var{branch}} from git.sv.gnu.org with
+
+@example
+git pull origin
+@end example
+
+Note that this command generally fetches all branches you added with
+@command{git remote add} (when you initialized the repository) or
+@command{git config --add}, i.e. it updates all remote branches from
+remote @code{origin}, then it merges the remote branch tracked by
+current branch into current branch. For example, if your current
+branch is @code{master} --- which is the case if you got the sources
+with the commands described in @ref{Main source code} and did not
+issue any @command{git checkout} command --- @code{origin/master} will
+be merged into @code{master}.
+
+
+@subsubheading Local clones, or having several working trees
+
+If you play with several Git branches, e.g. @code{master},
+@code{lilypond/translation}, @code{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
+@code{@var{branch}}, run
+
+@example
+git checkout @var{branch}
+git clone -l -s -n . @var{subdir}
+cd @var{subdir}
+git reset --hard
+@end example
+
+Note that @code{@var{subdir}} must be a directory name which does not
+already exist. In @code{@var{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 @code{@var{subdir}} and run @command{git pull}; to send changes
+made on the subrepository back to the main repository, run
+@command{git push} from @code{@var{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.
+
+When you push @code{@var{branch}} from @code{@var{subdir}} to the main
+repository, and @code{@var{branch}} is checked out in the main
+repository, you must save uncommitted changes (see @command{git
+stash}) and do @command{git reset --hard} in the main repository in
+order to apply pushed changes in the working tree of the main
+repository.
+
@node Sharing your changes
@section Sharing your changes
@node Producing a patch
@subsection Producing a patch
-Once you have finished editing your files, checked that your
-changes meet the @ref{Code style} and/or @ref{Documentation
-policy}, and checked that the entire thing compiles, you may
+Once you have finished editing your files, checked that your changes
+meet the @ref{Code style}, and/or @ref{Documentation policy}, properly
+set up your name and email in @ref{Git user configuration}, and
+checked that the entire thing compiles, you may
@example
git commit -a
@node Committing directly
@subsection Committing directly
-Most contributors do not have permission to commit directly. If
-you do, edit @file{.git/config} to contain
+Most contributors do not have permission to commit directly. If you
+do, make sure you have set up your name and email in @ref{Git user
+configuration}, then edit @file{.git/config}: change the line
@example
-FIXME? Is anything needed, or did the previous commands set it
-up?
+ url = git://git.sv.gnu.org/lilypond.git/
@end example
-You may then @code{git push}.
+@noindent
+into
+@example
+ url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
+@end example
+
+@noindent
+where @var{user} is your login name on Savannah.
+
+If you have not already done so, you should generate and upload a SSH
+key: open @uref{https://savannah.gnu.org/my/} in your browser, then go to
+@q{Preferences} then to something like @q{Edit SSH Keys}, and follow
+the instructions on that page.
+
+You may then
+
+@example
+git push origin
+@end example
@node Other interesting Git commands
For LilyPond files, you should follow the guidelines for LilyPond snippets
in the documentation. You can find these guidelines at
-@c FIXME: not a node @ref{LilyPond formatting}.
+@ref{Texinfo introduction and usage policy}.
@node Finding functions
@section Finding functions
progress ("Writing %s..." % status_txt_file)
open (status_txt_file, 'w').write (main_status_txt)
-translation_instructions_file = 'TRANSLATION'
+translation_instructions_file = 'devel/doc-translation-list.itexi'
progress ("Updating %s..." % translation_instructions_file)
translation_instructions = open (translation_instructions_file).read ()
projects / lilypond.git / commitdiff