+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.
projects / lilypond.git / blobdiff