]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/devel/doc-work.itexi
Doc-de: update macros.itely and nitpicks
[lilypond.git] / Documentation / devel / doc-work.itexi
index c3d264f12410131f872a9a97afff3a7aa66da3c9..2e447deb4c60aca5f15a989258c22181122cd889 100644 (file)
@@ -1,30 +1,30 @@
-@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::        
-* Documentation policy::        
-* Tips for writing docs::       
-* Updating docs with convert-ly::  
-* Translating the documentation::  
+* Introduction to documentation work::
+* Documentation suggestions::
+* Texinfo introduction and usage policy::
+* Documentation policy::
+* Tips for writing docs::
+* Updating docs with convert-ly::
+* Translating the documentation::
 @end menu
 
 
 @node Introduction to documentation work
 @section Introduction to documentation work
 
-Our documentation tries to adhere to the @ref{Documentation
-policy} as strictly as possible.  One policy in particular is
-often questioned by potential contributors: we do not repeat
-material in the Notation Reference, and instead provide links to
-the @qq{definitive} presentation of that information.
-
-Some people point out, with good reason, that this makes the
-documentation harder to read.  If we repeated certain information
-in relevant places, readers would be less likely to miss that
-information.
+Our documentation tries to adhere to our @ref{Documentation
+policy}.  This policy contains a few items which may seem odd.
+One policy in particular is often questioned by potential
+contributors: we do not repeat material in the Notation Reference,
+and instead provide links to the @qq{definitive} presentation of
+that information.  Some people point out, with good reason, that
+this makes the documentation harder to read.  If we repeated
+certain information in relevant places, readers would be less
+likely to miss that information.
 
 That reasoning is sound, but we have two counter-arguments.
 First, the Notation Reference -- one of @emph{five} manuals for
@@ -52,11 +52,115 @@ they also stem from attempting to find the most effective use of
 limited documentation help.
 
 
+@node Documentation suggestions
+@section Documentation suggestions
+
+@subheading Small additions
+
+For additions to the documentation,
+
+@enumerate
+
+@item
+Tell us where the addition should be placed. Please include both
+the section number and title (i.e. "LM 2.13 Printing lyrics").
+
+@item
+Please write exact changes to the text.
+
+@item
+A formal patch to the source code is @emph{not} required; we can
+take care of the technical details. Here is an example of a
+perfect documentation report:
+
+@verbatim
+To: lilypond-devel@gnu.org
+From: helpful-user@example.net
+Subject: doc addition
+
+In LM 2.13 (printing lyrics), above the last line ("More options,
+like..."), please add:
+
+----
+To add lyrics to a divided part, use blah blah blah.  For example,
+
+\score {
+  \notes {blah <<blah>> }
+  \lyrics {blah <<blah>> }
+  blah blah blah
+}
+----
+
+In addition, the second sentence of the first paragraph is
+confusing.  Please delete that sentence (it begins "Users
+often...") and replace it with this:
+----
+To align lyrics with something, do this thing.
+----
+
+Have a nice day,
+Helpful User
+@end verbatim
+
+@end enumerate
+
+
+@subheading Larger contributions
+
+To replace large sections of the documentation, the guidelines are
+stricter. We cannot remove parts of the current documentation
+unless we are certain that the new version is an improvement.
+
+@enumerate
+
+@item
+Ask on the lilypond-devel maillist if such a rewrite is necessary;
+somebody else might already be working on this issue!
+
+@item
+Split your work into small sections; this makes it much easier to
+compare the new and old documentation.
+
+@item
+Please prepare a formal git patch.
+
+@end enumerate
+
+Once you have followed these guidelines, please send a message to
+lilypond-devel with your documentation submissions. Unfortunately
+there is a strict “no top-posting” check on the mailist; to avoid
+this, add:
 
-@node Texinfo crash course
-@section Texinfo crash course
+> I'm not top posting.
+
+(you must include the > ) to the top of your documentation
+addition.
+
+We may edit your suggestion for spelling, grammar, or style, and
+we may not place the material exactly where you suggested, but if
+you give us some material to work with, we can improve the manual
+much faster.  Thanks for your interest!
+
+
+@node Texinfo introduction and usage policy
+@section Texinfo introduction and usage policy
+
+@menu
+* Texinfo introduction::
+* Documentation files::
+* 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
@@ -69,90 +173,175 @@ You can learn most of what you need to know from this; if you want
 to do anything fancy, discuss it on @code{lilypond-devel} first.}
 
 
+@node Documentation files
+@subsection Documentation files
+
+The user manuals lives in @file{Documentation/user/}.  In
+particular, the files @file{lilypond-learning.ly} (LM),
+@file{lilypond.itely} (NR), @file{music-glossary.tely} (MG), and
+@file{lilypond-program} (AU).  Each chapter is written in a
+separate file (ending in @file{.itely} for files containing
+lilypond code, and @file{.itexi} for files without lilypond code);
+see the @qq{main} file for each manual to determine the filename
+of the specific chapter you wish to modify.
+
+Developer manuals live in @file{Documentation/devel}.  Currently
+there is only one; @file{contrib-guide.texi}.
+
+Although snippets are part of documentation, they are not
+(directly) part of the manuals.  For information about how to
+modify them, see @ref{LSR work}.
+
+
+@node Sectioning commands
 @subsection Sectioning commands
 
 Most of the manual operates at the
-       @@node Foo
-       @@subsubsection Foo
+
+@example
+@@node Foo
+@@subsubsection Foo
+@end example
+
+@noindent
 level.  Sections are created with
-       @@node Foo
-       @@subsection Foo
-commands.
 
-* Please leave two blank lines above a @@node; this makes it easier
-  to findw sections in texinfo.
+@example
+@@node Foo
+@@subsection Foo
+@end example
 
-* sectioning commands (@@node and @@section) must not appear inside
-  an @@ignore.  Separate those commands with a space, ie @@n ode.
+@itemize
+@item
+Please leave two blank lines above a @@node; this makes it
+easier to find sections in texinfo.
 
+@item
+Sectioning commands (@@node and @@section) must not appear
+inside an @@ignore.  Separate those commands with a space, ie @@n
+ode.
 
+@end itemize
 
+
+@node LilyPond formatting
 @subsection LilyPond formatting
 
-* Use two spaces for indentation in lilypond examples.  (no tabs)
+@itemize
+
+@item
+Use two spaces for indentation in lilypond examples.  (no
+tabs)
+
+@item
+All text strings should be prefaced with #.  LilyPond does
+not strictly require this, but it is helpful to get users
+accustomed to this scheme construct.  ie @code{\set
+Staff.instrumentName = #"cello"}
+
+@item
+All engravers should have double-quotes around them:
+
+@example
+\consists "Spans_arpeggio_engraver"
+@end example
+
+Again, LilyPond does not strictly require this, but it is a useful
+standard to follow.
+
+@item
+Examples should end with a complete bar if possible.
+
+@item
+If possible, only write one bar per line.  The notes on each
+line should be an independent line -- tweaks should occur on their
+own line if possible.  Bad:
+
+@example
+\override textscript #'padding = #3 c1^"hi"
+@end example
+
+Good:
+
+@example
+\override textscript #'padding = #3
+c1^"hi"
+@end example
+
+@item
+Most LilyPond input should be produced with:
+
+@example
+@@lilypond[verbatim,quote,relative=2]
+@end example
+
+@noindent
+or
 
-* All text strings should be prefaced with #.  LilyPond does not
-  strictly require this, but it is helpful to get users accustomed
-  to this scheme construct.  ie
-    \set Staff.instrumentName = #"cello"
+@example
+@@lilypond[verbatim,quote,relative=1]
+@end example
 
-* All engravers should have double-quotes around them:
-    \consists "Spans_arpeggio_engraver"
-  Again, LilyPond does not strictly require this, but it is a
-  useful standard to follow.
+If you want to use \layout@{@} or define variables, use
 
-* Examples should end with a complete bar if possible.
+@example
+@@lilypond[verbatim,quote]
+@end example
 
-* If possible, only write one bar per line.  The notes on each
-  line should be an independent line -- tweaks should occur on
-  their own line if possible.
-  Bad:
-    \override textscript #'padding = #3 c1^"hi"
-  Good:
-    \override textscript #'padding = #3
-    c1^"hi"
+In rare cases, other options may be used (or omitted), but ask first.
 
-* Most LilyPond input should be produced with:
-    @@lilypond[verbatim,quote,relative=2]
-  or
-    @@lilypond[verbatim,quote,relative=1]
+@item
+Inspirational headwords are produced with
 
-  If you want to use \layout@{@} or define variables, use
-    @@lilypond[verbatim,quote]
+@example
+@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
+@{pitches-headword.ly@}
+@end example
 
-  In rare cases, other options may be used (or omitted), but ask first.
+@item
+LSR snippets are linked with
 
-* Inspirational headwords are produced with
-  @@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-  @{pitches-headword.ly@}
+@example
+@@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@{filename.ly@}
+@end example
+
+@noindent
+excepted in Templates, where `doctitle' may be omitted.
 
-* LSR snippets are linked with
-  @@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-  @{filename.ly@}
-  excepted in Templates, where `doctitle' may be omitted.
+@item
+Avoid long stretches of input code.  Noone is going to read
+them in print.  Please create a smaller example.  (the smaller
+example does not need to be minimal, however)
 
-* Avoid long stretches of input code.  Noone is going to read them
-  in print.  Please create a smaller example.  (the smaller
-  example does not need to be minimal, however)
+@item
+Specify durations for at least the first note of every bar.
 
-* Specify durations for at least the first note of every bar.
+@item
+If possible, end with a complete bar.
 
-* If possible, end with a complete bar.
+@item
+Comments should go on their own line, and be placed before
+the line(s) to which they refer.
 
-* Comments should go on their own line, and be placed before the
-  line(s) to which they refer.
+@item
+Add extra spaces around @{ @} marks; ie
 
-* Add extra spaces around @{ @} marks; ie
-  not:          \chordmode @{c e g@}
-  but instead:  \chordmode @{ c e g @}
+@example
+not:          \chordmode @{c e g@}
+but instead:  \chordmode @{ c e g @}
+@end example
 
-* If you only have one bar per line, omit bar checks.  If you
-  put more than one bar per line (not recommended), then include
-  bar checks.
+@item
+If you only have one bar per line, omit bar checks.  If you
+put more than one bar per line (not recommended), then include bar
+checks.
 
-* If you want to work on an example outside of the manual (for
-  easier/faster processing), use this header:
+@item
+If you want to work on an example outside of the manual (for
+easier/faster processing), use this header:
 
+@example
 \paper @{
   #(define dump-extents #t)
   indent = 0\mm
@@ -164,178 +353,277 @@ commands.
 
 \layout @{
 @}
+@end example
+
+You may not change any of these values.  If you are making an
+example demonstrating special \paper@{@} values, contact the
+Documentation Editor.
 
-  You may not change any of these values.  If you are making an
-  example demonstrating special \paper@{@} values, contact the
-  Documentation Editor.
+@end itemize
 
 
+@node Text formatting
 @subsection Text formatting
 
-* Lines should be less than 72 characters long.  (I personally
-  recommend writing with 66-char lines, but don't bother modifying
-  existing material.)
+@itemize
 
-* Do not use tabs.
+@item
+Lines should be less than 72 characters long.  (I personally
+recommend writing with 66-char lines, but don't bother modifying
+existing material.)
 
-* Do not use spaces at the beginning of a line (except in @@example
-  or @@verbatim environments), and do not use more than a single
-  space between words.  `makeinfo' copies the input lines verbatim
-  without removing those spaces.
+@item
+Do not use tabs.
 
-* Use two spaces after a period.
+@item
+Do not use spaces at the beginning of a line (except in
+@@example or @@verbatim environments), and do not use more than a
+single space between words.  `makeinfo' copies the input lines
+verbatim without removing those spaces.
 
-* In examples of syntax, use @@var@{musicexpr@} for a music
-  expression.
+@item
+Use two spaces after a period.
 
-* Don't use @@rinternals@{@} in the main text.  If you're tempted to
-  do so, you're probably getting too close to "talking through the
-  code".  If you really want to refer to a context, use @@code@{@} in
-  the main text and @@rinternals@{@} in the @@seealso.
+@item
+In examples of syntax, use @@var@{musicexpr@} for a music
+expression.
 
-* Variables or numbers which consist of a single character
-  (probably followed by a punctuation mark) should be tied
-  properly, either to the previous or the next word.  Example:
+@item
+Don't use @@rinternals@{@} in the main text.  If you're
+tempted to do so, you're probably getting too close to "talking
+through the code".  If you really want to refer to a context, use
+@@code@{@} in the main text and @@rinternals@{@} in the @@seealso.
 
-      The variable@@tie@{@}@@var@{a@} ...
+@item
+Variables or numbers which consist of a single character
+(probably followed by a punctuation mark) should be tied properly,
+either to the previous or the next word.  Example:
 
-* To get consistent indentation in the DVI output it is better to
-  avoid the @@verbatim environment.  Use the @@example environment
-  instead if possible, but without extraneous indentation.  For
-  example, this
+@example
+The variable@@tie@{@}@@var@{a@} ...
+@end example
 
-    @@example
-      foo @{
-        bar
-      @}
-    @@end example
+@item
+To get consistent indentation in the DVI output it is better
+to avoid the @@verbatim environment.  Use the @@example
+environment instead if possible, but without extraneous
+indentation.  For example, this
 
-  should be replaced with
+@example
+@@example
+  foo @{
+    bar
+  @}
+@@end example
+@end example
 
-    @@example
-    foo @{
-      bar
-    @}
-    @@end example
+@noindent
+should be replaced with
+
+@example
+@@example
+foo @{
+  bar
+@}
+@@end example
+@end example
 
-  where `@@example' starts the line (without leading spaces).
+@noindent
+where `@@example' starts the line (without leading spaces).
 
-* Do not compress the input vertically; this is, do not use
+@item
+Do not compress the input vertically; this is, do not use
 
+@example
     Beginning of logical unit
     @@example
     ...
     @@end example
     continuation of logical unit
+@end example
 
-  but
+@noindent
+but instead do
 
-    Beginning of logical unit
+@example
+Beginning of logical unit
 
-    @@example
-    ...
-    @@end example
+@@example
+...
+@@end example
 
-    @@noindent
-    continuation of logical unit
+@@noindent
+continuation of logical unit
+@end example
 
-  This makes it easier to avoid forgetting the `@@noindent'.  Only
-  use @@noindent if the material is discussing the same material;
-  new material should simply begin without anything special on the
-  line above it.
+This makes it easier to avoid forgetting the `@@noindent'.  Only
+use @@noindent if the material is discussing the same material;
+new material should simply begin without anything special on the
+line above it.
 
-* in @@itemize use @@item on a separate line like this:
-  @@itemize
-  @@item
-  Foo
+@item
+in @@itemize use @@item
+on a separate line like this:
 
-  @@item
-  Bar
+@example
+@@itemize
+@@item
+Foo
 
-  Do not use @@itemize @@bullet.
+@@item
+Bar
+@end example
 
-* To get LilyPond version, use @@version@{@} (this does not work inside
-  LilyPond snippets).  If you write "@@version@{@}" (enclosed with
-  quotes), or generally if @@version@{@} is not followed by a space,
-  enclose it with
+Do not use @@itemize @@bullet.
 
-  @@w@{ ... @}
+@item
+To get LilyPond version, use @@version@{@} (this does not work
+inside LilyPond snippets).  If you write "@@version@{@}" (enclosed
+with quotes), or generally if @@version@{@} is not followed by a
+space, tere will be an ugly line break in PDF output unless you
+enclose it with
+
+@example
+@@w@{ ... @}
 
   e.g.
 
-  @@w@{"@@version@{@}"@}
+@@w@{"@@version@{@}"@}
+@end example
 
-  to prevent an ugly line break in PDF output.
+@end itemize
 
 
+@node Syntax survey
 @subsection Syntax survey
 
+@itemize
+@item
 @@c - single line comments
   "@@c NOTE:" is a comment which should remain in the final
   version.  (gp only command ;)
+@item
 @@ignore ... @@end ignore - multi-line comment
 
+@item
 @@cindex - General index. Please add as many as you can.  Don't
   capitalize the first word.
+@item
 @@funindex - is for a \lilycommand.
 
+@item
 @@example ... @@end ignore - example text that should be set as a
   blockquote.  Any @{@} must be escaped with @@@{ @}@@
-@@itemize @@item A @@item B ... @@end itemize - for bulleted lists.
+@item
+@@itemize @@item
+A @@item
+B ... @@end itemize - for bulleted lists.
   Do not compress vertically like this.
 
+@item
 @@code@{@} - typeset in a tt-font. Use for actual lilypond code or
   property/context names.  If the name contains a space, wrap
   the entire thing inside @@w@{@@code@{  @}@}.
+@item
 @@notation@{@} - refers to pieces of notation, e.g.
   "@@notation@{cres.@}".  Also use to specific lyrics ("the
   @@notation@{A - men@} is centered").  Only use once per subsection
   per term.
+@item
 @@q@{@} - Single quotes. Used for `vague' terms.
+@item
 @@qq@{@} - Double quotes.  Used for actual quotes ("he said") or for
   introducing special input modes.
 
+@item
 @@tie@{@} - Variables or numbers which consist of a single character
   (probably followed by a punctuation mark) should be tied
   properly, either to the previous or the next word.  Example:
     "The letter@@tie@{@}@@q@{I@} is skipped"
 
+@item
 @@var - Use for variables.
+@item
 @@warning@{@} - produces a "Note: " box. Use for important messages.
 
+@item
 @@bs - Generates a backslash inside @@warning.
-    Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}' 
+    Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}'
     (texinfo would also allow \\, but this breaks with PDF output).
 
+@item
+@@ref@{@} - normal references (type the exact node name inside the
+@{@}).
+@item
+@@ruser@{@} - link to the NR.
+@item
+@@rlearning@{@} - link to the LM.
+@item
+@@rglos@{@} - link to the MG.
+@item
+@@rprogram@{@} - link to the AU.
+@item
+@@rlsr@{@} - link to a Snippet section.
+@item
+@@rinternals@{@} - link to the IR.
+@item
+@@uref@{@} - link to an external url.
+
+@end itemize
+
+
+
+@node Other text concerns
+@subsection Other text concerns
 
+@itemize
 
-@subsection Other text concerns
+@item
+References must occur at the end of a sentence, for more
+information see @@ref@{the texinfo manual@}.  Ideally this should
+also be the final sentence of a paragraph, but this is not
+required.  Any link in a doc section must be duplicated in the
+@@seealso section at the bottom.
 
-* References must occur at the end of a sentence, for more
-  information see @@ref@{the texinfo manual@}.  Ideally this should
-  also be the final sentence of a paragraph, but this is not
-  required.  Any link in a doc section must be duplicated in the
-  @@seealso section at the bottom.
+@item
+Introducing examples must be done with
 
-* Introducing examples must be done with
+@example
      . (ie finish the previous sentence/paragaph)
      : (ie `in this example:')
      , (ie `may add foo with the blah construct,')
-  The old "sentence runs directly into the example" method is not
-  allowed any more.
+@end example
+
+The old "sentence runs directly into the example" method is not
+allowed any more.
+
+@item
+Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
+
+@item
+Colon usage
+
+@enumerate
+
+@item
+To introduce lists
 
-* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
+@item
+When beginning a quote: "So, he said,...".
 
-* Colon usage
+This usage is rarer.  Americans often just use a comma.
 
-  1. To introduce lists
-  2. When beginning a quote: "So, he said,..."
-     This usage is rarer.  Americans often just use a comma.
-  3. When adding a defining example at the end of a sentence.
+@item
+When adding a defining example at the end of a sentence.
 
-* Non-ASCII characters which are in utf-8 should be directly used;
-  this is, don't say `Ba@@ss@{@}tuba' but `Baßtuba'.  This ensures that
-  all such characters appear in all output formats.
+@end enumerate
+
+@item
+Non-ASCII characters which are in utf-8 should be directly used;
+this is, don't say `Ba@@ss@{@}tuba' but `Baßtuba'.  This ensures
+that all such characters appear in all output formats.
+
+@end itemize
 
 
 
@@ -343,43 +631,56 @@ commands.
 @node Documentation policy
 @section Documentation policy
 
+@menu
+* Books::
+* Section organization::
+* Checking cross-references::
+* General writing::
+* Technical writing style::
+@end menu
 
+@node Books
 @subsection Books
 
 There are four parts to the documentation: the Learning Manual,
 the Notation Reference, the Program Reference, and the Music
 Glossary.
 
-* Learning Manual:
-  The LM is written in a tutorial style which introduces the most
-  important concepts, structure and syntax of the elements of a
-  LilyPond score in a carefully graded sequence of steps.
-  Explanations of all musical concepts used in the Manual can be
-  found in the Music Glossary, and readers are assumed to have no
-  prior knowledge of LilyPond.  The objective is to take readers to
-  a level where the Notation Reference can be understood and
-  employed to both adapt the templates in the Appendix to their
-  needs and to begin to construct their own scores.  Commonly used
-  tweaks are introduced and explained.  Examples are provided
-  throughout which, while being focussed on the topic being
-  introduced, are long enough to seem real in order to retain the
-  readers' interest.  Each example builds on the previous material,
-  and comments are used liberally.  Every new aspect is thoroughly
-  explained before it is used.
+@itemize
+
+@item
+Learning Manual:
+
+The LM is written in a tutorial style which introduces the most
+important concepts, structure and syntax of the elements of a
+LilyPond score in a carefully graded sequence of steps.
+Explanations of all musical concepts used in the Manual can be
+found in the Music Glossary, and readers are assumed to have no
+prior knowledge of LilyPond.  The objective is to take readers to
+a level where the Notation Reference can be understood and
+employed to both adapt the templates in the Appendix to their
+needs and to begin to construct their own scores.  Commonly used
+tweaks are introduced and explained.  Examples are provided
+throughout which, while being focussed on the topic being
+introduced, are long enough to seem real in order to retain the
+readers' interest.  Each example builds on the previous material,
+and comments are used liberally.  Every new aspect is thoroughly
+explained before it is used.
 
 Users are encouraged to read the complete Learning Manual from
 start-to-finish.
 
 
-* Notation Reference: a (hopefully complete) description of
-  LilyPond input notation.  Some material from here may be
-  duplicated in the Learning Manual (for teaching), but consider
-  the NR to be the "definitive" description of each notation
-  element, with the LM being an "extra".  The goal is _not_ to
-  provide a step-by-step learning environment -- do not avoid
-  using notation that has not be introduced previously in the
-  NR  (for example, use \break if appropriate).  This section is
-  written in formal technical writing style.
+@item
+Notation Reference: a (hopefully complete) description of LilyPond
+input notation.  Some material from here may be duplicated in the
+Learning Manual (for teaching), but consider the NR to be the
+"definitive" description of each notation element, with the LM
+being an "extra".  The goal is _not_ to provide a step-by-step
+learning environment -- do not avoid using notation that has not
+be introduced previously in the NR  (for example, use \break if
+appropriate).  This section is written in formal technical writing
+style.
 
 Avoid duplication.  Although users are not expected to read this
 manual from start to finish, they should be familiar with the
@@ -387,9 +688,8 @@ material in the Learning Manual (particularly ``Fundamental
 Concepts''), so do not repeat that material in each section of
 this book.  Also watch out for common constructs, like ^ - _ for
 directions -- those are explained in NR 3.  In NR 1, you can
-write:
-DYNAMICS may be manually placed above or below the
-staff, see @@ref@{Controlling direction and placement@}.
+write: DYNAMICS may be manually placed above or below the staff,
+see @@ref@{Controlling direction and placement@}.
 
 Most tweaks should be added to LSR and not placed directly in the
 .itely file.  In some cases, tweaks may be placed in the main
@@ -399,204 +699,304 @@ Finally, you should assume that users know what the notation
 means; explaining musical concepts happens in the Music Glossary.
 
 
-* Application Usage: information about using the program lilypond
-  with other programs (lilypond-book, operating systems, GUIs,
-  convert-ly, etc).  This section is written in formal technical
-  writing style.
+@item
+Application Usage: information about using the program lilypond
+with other programs (lilypond-book, operating systems, GUIs,
+convert-ly, etc).  This section is written in formal technical
+writing style.
 
 Users are not expected to read this manual from start to finish.
 
 
-* Music Glossary: information about the music notation itself.
-  Explanations and translations about notation terms go here.
+@item
+Music Glossary: information about the music notation itself.
+Explanations and translations about notation terms go here.
 
 Users are not expected to read this manual from start to finish.
 
-* Internals Reference: not really a documentation book, since it
-  is automagically generated from the source, but this is its
-  name.
+@item
+Internals Reference: not really a documentation book, since it is
+automagically generated from the source, but this is its name.
+
+@end itemize
 
 
+@node Section organization
 @subsection Section organization
 
-The order of headings inside documentation sections should be:
+@itemize
+
+@item
+The order of headings inside documentation sections should
+be:
 
+@example
 main docs
 @@predefined
 @@endpredefined
 @@snippets
 @@seealso
 @@knownissues
+@end example
 
-* You _must_ include a @@seealso.  The order of items inside the
-  @@seealso section is
+@item
+You @emph{must} include a @@seealso.
 
-    Music Glossary:
-    @@rglos@{foo@},
-    @@rglos@{bar@}.
+@itemize
+@item
+The order of items inside the @@seealso section is
 
-    Learning Manual:
-    @@rlearning@{baz@},
-    @@rlearning@{foozle@}.
+@example
+Music Glossary:
+@@rglos@{foo@},
+@@rglos@{bar@}.
 
-    Notation Reference:
-    @@ruser@{faazle@},
-    @@ruser@{boo@}.
+Learning Manual:
+@@rlearning@{baz@},
+@@rlearning@{foozle@}.
 
-    Application Usage:
-    @@rprogram@{blah@}.
+Notation Reference:
+@@ruser@{faazle@},
+@@ruser@{boo@}.
 
-    Installed Files:
-    @@file@{path/to/dir/blahz@}.
+Application Usage:
+@@rprogram@{blah@}.
 
-    Snippets: @@rlsr@{section@}.
+Installed Files:
+@@file@{path/to/dir/blahz@}.
 
-    Internals Reference:
-    @@rinternals@{fazzle@},
-    @@rinternals@{booar@}.
+Snippets: @@rlsr@{section@}.
+
+Internals Reference:
+@@rinternals@{fazzle@},
+@@rinternals@{booar@}.
+@end example
 
-      If there are multiple entries, separate them by commas
-      but do not include an `and'.
+@item
+If there are multiple entries, separate them by commas but do not
+include an `and'.
 
-      Always end with a period.
+@item
+Always end with a period.
 
-      Place each link on a new line as above; this makes it much
-      easier to add or remove links.  In the output, they
-      appear on a single line.
+@item
+Place each link on a new line as above; this makes it much easier
+to add or remove links.  In the output, they appear on a single
+line.
 
-  ("Snippets" is REQUIRED; the others are optional)
+("Snippets" is REQUIRED; the others are optional)
 
-  Any new concepts or links which require an explanation should go
-  as a full sentence(s) in the main text.
+@item
+Any new concepts or links which require an explanation should go
+as a full sentence(s) in the main text.
 
-  Don't insert an empty line between @@seealso and the first entry!
-  Otherwise there is excessive vertical space in the PDF output.
+@item
+Don't insert an empty line between @@seealso and the first entry!
+Otherwise there is excessive vertical space in the PDF output.
 
-* To create links, use @@ref@{@} if the link is within the same
-  manual.
+@end itemize
 
-* @@predefined ... @@endpredefined is for commands in ly/*-init.ly
-  FIXME?
+@item
+To create links, use @@ref@{@} if the link is within the same
+manual.
 
-* Do not include any real info in second-level sections (ie 1.1
-  Pitches).  A first-level section may have introductory material,
-  but other than that all material goes into third-level sections
-  (ie 1.1.1 Writing Pitches).
+@item
+@@predefined ... @@endpredefined is for commands in ly/*-init.ly
+FIXME?
 
+@item
+Do not include any real info in second-level sections (ie 1.1
+Pitches).  A first-level section may have introductory material,
+but other than that all material goes into third-level sections
+(ie 1.1.1 Writing Pitches).
 
+@end itemize
+
+
+@node Checking cross-references
 @subsection Checking cross-references
 
 Cross-references between different manuals are heavily used in the
-documentation, but they are not checked during compilation.  However,
-if you compile the documentation, a script called check_texi_refs can
-help you with checking and fixing these cross-references; for
-information on usage, cd into a source tree where documentation has
-been built, cd into Documentation and look for check-xrefs and
-fix-xrefs targets in 'make help' output.  Note that you have to find
-yourself the source files to fix cross-references in the generated
-documentation such as the Internals Reference; e.g. you can grep
-scm/ and lily/.
+documentation, but they are not checked during compilation.
+However, if you compile the documentation, a script called
+check_texi_refs can help you with checking and fixing these
+cross-references; for information on usage, cd into a source tree
+where documentation has been built, cd into Documentation and look
+for check-xrefs and fix-xrefs targets in 'make help' output.  Note
+that you have to find yourself the source files to fix
+cross-references in the generated documentation such as the
+Internals Reference; e.g. you can grep scm/ and lily/.
+
+
+@node General writing
+@subsection General writing
 
+@itemize
 
-@subsection General writing
+@item
+Do not forget to create @@cindex entries for new sections of text.
+Enter commands with @@funindex, i.e.
+
+@example
+@@cindex pitches, writing in different octaves
+@@funindex \relative
+@end example
+
+@noindent
+do not bother with the @@code@{@} (they are added automatically).
+These items are added to both the command index and the unified
+index.
+
+Both index commands should go in front of the actual material.
+
+@@cindex entries should not be capitalized, ie
+
+@example
+@@cindex time signature
+@end example
+
+@noindent
+is preferred instead of @qq{Time signature},   Only use capital
+letters for musical terms which demand them, like D.S. al Fine.
+
+For scheme functions, only include the final part, i.e.,
+
+@example
+@@funindex modern-voice-cautionary
+     and NOT
+@@funindex #(set-accidental-style modern-voice-cautionary)
+@end example
+
+@item
+Preferred terms:
+
+@itemize
 
-* Do not forget to create @@cindex entries for new sections of text.
-  Enter commands with @@funindex, i.e.
-    @@cindex pitches, writing in different octaves
-    @@funindex \relative
-  do not bother with the @@code@{@} (they are added automatically).  These
-  items are added to both the command index and the unified index.
-
-  Both index commands should go in front of the actual material.
-
-  @@cindex entries should not be capitalized, ie
-    @@cindex time signature
-  is preferred.  (instead of `Time signature')   Only use capital
-  letters for musical terms which demand them, like D.S. al Fine.
-
-  For scheme functions, only include the final part, ie
-    @@funindex modern-voice-cautionary
-  and NOT
-    @@funindex #(set-accidental-style modern-voice-cautionary)
-
-* Preferred terms:
-    - in general, use the American spellings.  The internal
-      lilypond property names use this spelling.
-    - list of specific terms:
+@item
+In general, use the American spellings.  The internal lilypond
+property names use this spelling.
+
+@item
+List of specific terms:
+
+@example
 canceled
-simultaenous    NOT concurrent
+simultaneous    NOT concurrent
 measure: the unit of music
 bar line: the symbol delimiting a measure   NOT barline
 note head   NOT notehead
 chord construct   NOT chord (when referring to <>)
+@end example
+
+@end itemize
+
+@end itemize
 
 
+@node Technical writing style
 @subsection Technical writing style
 
-* Do not refer to LilyPond in the text.  The reader knows what the
-  manual is about.  If you do, capitalization is LilyPond.
+These refer to the NR.  The LM uses a more gentle, colloquial
+style.
 
-* If you explicitly refer to `lilypond' the program (or any other
-  command to be executed), say `@@command@{lilypond@}'.
+@itemize
 
-* Do not explicitly refer to the reader/user.  There is no one
-  else besides the reader and the writer.
+@item
+Do not refer to LilyPond in the text.  The reader knows what the
+manual is about.  If you do, capitalization is LilyPond.
 
-* Do not use abbreviations (don't, won't, etc.).  If you do, use a
-  comma after it:
+@item
+If you explicitly refer to @q{lilypond} the program (or any other
+command to be executed), write @code{@@command@{lilypond@}}.
 
-    blabla blabla, i.e., blabla blabla
+@item
+Do not explicitly refer to the reader/user.  There is no one else
+besides the reader and the writer.
 
-* Avoid fluff (``Notice that,'' ``as you can see,''
-  ``Currently,'').
+@item
+Avoid contractions (don't, won't, etc.).  Spell the words out completely.
 
-* The use of the word `illegal' is inappropriate in most cases.
-  Say `invalid' instead.
+@item
+Avoid abbreviations, except for commonly used abbreviations of foreign
+language terms such as etc. and i.e.
+
+@item
+Avoid fluff (@qq{Notice that,} @qq{as you can see,}
+@qq{Currently,}).
+
+@item
+The use of the word @q{illegal} is inappropriate in most cases.
+Say @q{invalid} instead.
+
+@end itemize
 
 
 @node Tips for writing docs
 @section Tips for writing docs
 
-In the NR, I highly recommend working on one subsection at a time.
-For each subsection,
-
-- check the mundane formatting.  Are the headings (@@predefined,
-  @@seealso, etc) in the right order?
-- add any appropriate index entries.
-- check the links in the @@seealso section -- links to music
-  glossary, internal references, and other NR sections are the
-  main concern.  Check for potential additions.
-- move LSR-worthy material into LSR.  Add the snippet (or
-  just send it to Valentin for adding), delete the material from
-  the .itely file, and add a @@lilypondfile command.
-
-- check the examples and descriptions.  Do they still work?
-  *Do not* assume that the existing text is accurate/complete;
-  some of the manual is highly out of date.
-- is the material in the @@knownissues  still accurate?
-- process anything on the TODO list on the GDP web site.
-- can the examples be improved (made more explanatory), or is
-  there any missing info?  (feel free to ask specific questions
-  on -user; a couple of people claimed to be interesting in being
-  "consultants" who would help with such questions)
+In the NR, I highly recommend focusing on one subsection at a
+time.  For each subsection,
+
+@itemize
+
+@item
+check the mundane formatting.  Are the headings (@@predefined,
+@@seealso, etc.) in the right order?
+
+@item
+add any appropriate index entries.
+
+@item
+check the links in the @@seealso section -- links to music
+glossary, internal references, and other NR sections are the main
+concern.  Check for potential additions.
+
+@item
+move LSR-worthy material into LSR.  Add the snippet, delete the
+material from the .itely file, and add a @@lilypondfile command.
+
+@item
+check the examples and descriptions.  Do they still work?
+@strong{Do not} assume that the existing text is
+accurate/complete; some of the manual is highly out of date.
+
+@item
+is the material in the @@knownissues  still accurate?
+
+@item
+can the examples be improved (made more explanatory), or is there
+any missing info?  (feel free to ask specific questions on -user;
+a couple of people claimed to be interesting in being
+@qq{consultants} who would help with such questions)
+
+@end itemize
 
 In general, I favor short text explanations with good examples --
-"an example is worth a thousand words".  When I worked on the
+@qq{an example is worth a thousand words}.  When I worked on the
 docs, I spent about half my time just working on those tiny
 lilypond examples.  Making easily-understandable examples is much
 harder than it looks.
 
 
-TWEAKS
+@subsubheading Tweaks
 
 In general, any \set or \override commands should go in the
-"select snippets" section, which means that they should go in LSR
-and not the .itely file.  For some cases, the command obviously
-belongs in the "main text" (ie not inside @@predefined or @@seealso
-or whatever) -- instrument names are a good example of this.
-  \set Staff.instrumentName = #"foo"
+@qq{select snippets} section, which means that they should go in
+LSR and not the .itely file.  For some cases, the command
+obviously belongs in the @qq{main text} (i.e. not inside
+@@predefined or @@seealso or whatever) -- instrument names are a
+good example of this.
+
+@example
+\set Staff.instrumentName = #"foo"
+@end example
+
 On the other side of this,
-  \override Score.Hairpin #'after-line-breaking = ##t
+
+@example
+\override Score.Hairpin #'after-line-breaking = ##t
+@end example
+
 clearly belongs in LSR.
 
 I'm quite willing to discuss specific cases if you think that a
@@ -605,62 +1005,672 @@ LSR are easier to maintain, so I'd like to move as much as
 possible into there.
 
 
-It would be "nice" if you spent a lot of time crafting nice tweaks
-for users... but my recommendation is *not* to do this.  There's a
-lot of doc work to do without adding examples of tweaks.  Tweak
-examples are trivial to add later -- they could be made by normal
-users, or by you after GDP is over.
+It would be @qq{nice} if you spent a lot of time crafting nice
+tweaks for users... but my recommendation is @strong{not} to do
+this.  There's a lot of doc work to do without adding examples of
+tweaks.  Tweak examples can easily be added by normal users by adding
+them to the LSR.
 
-Basically, it's not something that needs to be done while I'm
-around.  Remember that I'm gone in August at the latest; there's a
-*lot* of doc work that should be done before then.  I strongly
-recommend that you save all the tweaks until later.
+One place where a documentation writer can profitably spend time writing
+or upgrading tweaks is creating tweaks to deal with known issues.  It
+would be ideal if every significant known issue had a workaround to avoid
+the difficulty.
 
+@seealso
 
-FINAL
+@ref{Adding and editing snippets}.
 
-- when you think you're finished, let me know.  I'll spend a few
-  minutes and send you a list of mistakes to fix.
-  (there's a *lot* of details to cover; we'll probably spend a
-  week going back and forth like this.  See earlier warning about
-  hating me by the time you're done with a doc section :)
-- I'll ask people on -user to review the Snippet list at this
-  time; correcting things on the Snippet list is much easier than
-  getting comments on the integrated snippets.
-- when we're both satisfied with the section, we'll invite
-  comments from -user.  Judging from my experience with Pitches,
-  it will take between three and five weeks to keep on revising
-  the "final" version.
 
-I personally found it quite frustrating to still be fixing
-problems in a doc section which I thought was "perfect" a whole
-bloody *month* ago.  Don't get me wrong; it's great that we get so
-many comments from -user.  :)   But just be aware that when you
-think you're finally done with a section, you're actually only
-halfway there.
+@node Updating docs with convert-ly
+@section Updating doc with @command{convert-ly}
 
+cd into Documentation and run
 
+@example
+find . -name '*.itely' | xargs convert-ly -e
+@end example
 
+@noindent
+This also updates translated documentation.
 
 
 
+@node Translating the documentation
+@section Translating the documentation
 
-@node Updating docs with convert-ly
-@section Updating doc with convert-ly
+@menu
+* Getting started with documentation translation::
+* Documentation translation details::
+* Documentation translation maintenance::
+* Translations management policies::
+* Technical background::
+* Translation status::
+@end menu
 
-cd into Documentation and run
+@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
-find . -name '*.itely' | xargs convert-ly -e
+./autogen.sh
 @end example
 
 @noindent
-(This also updates translated docs.)
+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
 
-@node Translating the documentation
-@section Translating the documentation
+@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  @@ruser  @@rlearning  @@rprogram  @@rlsr
+@end example
+
+The same applies to first argument of @code{@@r@var{manual}named}
+commands; however, the second argument @var{Bar baz} of
+@code{@@ref@{@var{Foo},@var{Bar baz},,@var{info-file}@}} and
+@code{@@r@var{manual}named@{@var{Foo},@var{Bar baz}@}} 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
+doc}).  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 doc}) compile succesfully.
+
+@item @code{master} Git branch may be merged into
+@code{lilypond/translation} whenever @command{make} and @command{make
+doc} 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 Translation status
+@subsection Translation status