To organize multiple authors working on the documentation, we use a
Version Control System (VCS) called git, previously discussed in
-@ref{Starting with git}.
+@ref{Starting with Git}.
@menu
* Introduction to documentation work::
* Texinfo introduction and usage policy::
* Documentation policy::
* Tips for writing docs::
-* Updating docs with convert-ly::
+* Scripts to ease doc work::
* Docstrings in scheme::
* Translating the documentation::
@end menu
of the specific chapter you wish to modify.
Developer manuals live in @file{Documentation/} too. Currently there is
-only one: the Contributors' Guide @file{contrib-guide.texi} you are
+only one: the Contributor's Guide @file{contrib-guide.texi} you are
reading.
Snippet files are part of documentation, and the Snippet List (SL) lives
@end example
@noindent
-construct. These are easily constructed with the emacs
-@code{M-x texinfo-all-menus-update} construct, or by this
-command-line script:
-
-@example
-#!/bin/sh
-emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
-@end example
-
-@noindent
-(save the above as something like @command{texinfo-menus.sh}, make
-it executable, then run @command{texinfo-menus.sh foo.itely})
+construct. These are easily constructed with automatic tools; see
+@ref{Scripts to ease doc work}.
@node LilyPond formatting
standard to follow.
@item
-Examples should end with a complete bar if possible.
+If possible, only write one bar per line.
+
+@item
+If you only have one bar per line, omit bar checks. If you
+must put more than one bar per line (not recommended), then include bar
+checks.
@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:
+Tweaks should, if possible, also occur on their own line.
+Bad:
@example
\override textscript #'padding = #3 c1^"hi"
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. Nobody is going to read
+them in print. Create small examples. However, this does not mean
+it has be minimal.
@item
Specify durations for at least the first note of every bar.
but instead: \chordmode @{ c e g @}
@end example
-@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.
-
@item
If you want to work on an example outside of the manual (for
easier/faster processing), use this header:
@itemize
@item
-Lines should be less than 72 characters long. (I personally
-recommend writing with 66-char lines, but don't bother modifying
-existing material.)
+Lines should be less than 72 characters long. (We personally
+recommend writing with 66-char lines, but do not bother modifying
+existing material). However, see the note below regarding line
+lengths within @code{@@example} blocks.
+
+@item
+Individual lines within an @code{@@example} block should not
+exceed 74 characters; otherwise they will run into the margin in
+the pdf output, and may get clipped. If an @code{@@example} block
+is part of an @code{@@item} within an @code{@@itemize} or
+@code{@@enumerate} block, each line of the @code{@@example} should
+not exceed 70 columns---each additional level of @code{@@itemize}
+or @code{@@enumerate} shortens the line by about 4 columns.
+
+For command line examples, if possible, use a trailing backslash
+to break up a single line, indenting the next line with 2 spaces.
+If this isn't feasible, use @code{@@smallexample ...
+@@end@tie{}smallexample} instead, which uses a smaller fontsize.
+Use @code{@@example} whenever possible, but if needed,
+@code{@@smallexample} can fit up to 96 characters per line before
+running into the pdf margin. Each additional level of
+@code{@@itemize} or @code{@@enumerate} shortens a
+@code{@@smallexample} line by about 5 columns.
@item
Do not use tabs.
@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.
+@code{@@example} or @code{@@verbatim} environments), and do not
+use more than a single space between words. @q{makeinfo} copies
+the input lines verbatim without removing those spaces.
@item
Use two spaces after a period.
@item
-In examples of syntax, use @@var@{musicexpr@} for a music
-expression.
+In examples of syntax, use @code{@@var@{@var{musicexpr}@}} for a
+music expression.
@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.
+Don't use @code{@@rinternals@{@}} in the main text. If you're
+tempted to do so, you're probably getting too close to @qq{talking
+through the code}. If you really want to refer to a context, use
+@code{@@code@{@}} in the main text and @code{@@rinternals@{@}} in
+the @code{@@seealso}.
@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:
+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:
@example
The variable@@tie@{@}@@var@{a@} ...
@end example
@item
-To get consistent indentation in the DVI output it is better
-to avoid the @@verbatim environment. Use the @@example
+To get consistent indentation in the DVI output it is better to
+avoid the @code{@@verbatim} environment. Use the @code{@@example}
environment instead if possible, but without extraneous
indentation. For example, this
@end example
@noindent
-where `@@example' starts the line (without leading spaces).
+where @q{@code{@@example}} starts the line (without leading
+spaces).
@item
-Do not compress the input vertically; this is, do not use
+Do not compress the input vertically; that is, do not use
@example
- Beginning of logical unit
- @@example
- ...
- @@end example
- continuation of logical unit
+Beginning of logical unit
+@@example
+...
+@@end example
+continuation of logical unit
@end example
@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 remember the @q{@code{@@noindent}}. Only
+use @code{@@noindent} if the material is discussing the same
+material; new material should simply begin without anything
+special on the line above it.
@item
-in @@itemize use @@item
-on a separate line like this:
+in @code{@@itemize} and @code{@@enumerate} blocks, use
+@code{@@item} on a separate line like this:
@example
@@itemize
Bar
@end example
-Do not use @@itemize @@bullet.
+Do not use @code{@@itemize@tie{}@@bullet}.
@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, there will be an ugly line break in PDF output unless you
-enclose it with
+To get LilyPond version, use @code{@@version@{@}} (this does not
+work inside LilyPond snippets). If you write
+@code{"@@version@{@}"} (enclosed with quotes), or generally if
+@code{@@version@{@}} is not followed by a space, there will be an
+ugly line break in PDF output unless you enclose it with
@example
@@w@{ ... @}
@itemize
@item
-@@c - single line comments
- "@@c NOTE:" is a comment which should remain in the final
- version. (gp only command ;)
+@code{@@bs} --- Generates a backslash inside @code{@@warning}.
+Any @q{@bs{}} used inside @code{@@warning} (and @code{@@q} or
+@code{@@qq}) must be written as @q{@code{@@bs@{@}}} (texinfo would
+also allow @q{@bs{}@bs{}}, but this breaks with PDF output).
+
@item
-@@ignore ... @@end ignore - multi-line comment
+@code{@@c} --- single line comments. @qq{@code{@@c NOTE:}} is a
+comment which should remain in the final version. (gp only
+command ;)
@item
-@@cindex - General index. Please add as many as you can. Don't
- capitalize the first word.
+@code{@@cindex} --- General index. Please add as many as you can.
+Don't capitalize the first word.
+
@item
-@@funindex - is for a \lilycommand.
+@code{@@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 @code{@@w@{@@code@{ @}@}}.
@item
-@@example ... @@end example - example text that should be set as a
- blockquote. Any @{@} must be escaped with @@@{ @}@@
+@code{@@example ... @@end example} --- example text that should be
+set as a blockquote. Any @code{@{@tie{}@}} must be escaped with
+@code{@@@{@tie{}@@@}}.
@item
-@@itemize @@item
-A @@item
-B ... @@end itemize - for bulleted lists.
- Do not compress vertically like this.
+@code{@@funindex} --- is for a \lilycommand.
@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@{ @}@}.
+@code{@@ignore ... @@end ignore} --- multi-line comment
@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.
+@code{@@itemize @@item A @@item B ... @@end itemize} --- for
+bulleted lists. Do not compress vertically like this.
@item
-@@q@{@} - Single quotes. Used for `vague' terms.
+@code{@@notation@{@}} --- refers to pieces of notation, e.g.
+@qq{@code{@@notation@{clef}.@}}. Also use for specific lyrics
+(@qq{the @code{@@notation@{}A@tie{}-@tie{}men@} is centered}).
+Only use once per subsection per term.
@item
-@@qq@{@} - Double quotes. Used for actual quotes ("he said") or for
- introducing special input modes.
+@code{@@q@{@}} --- Single quotes. Used for @q{vague} terms.
@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"
+@code{@@qq@{@}} --- Double quotes. Used for actual quotes (@qq{he
+said}) or for introducing special input modes.
@item
-@@var - Use for variables.
+@code{@@rchanges@{@}} --- link to Changes.
@item
-@@warning@{@} - produces a "Note: " box. Use for important messages.
+@code{@@rcontrib@{@}} --- link to Contributor's Guide.
@item
-@@bs - Generates a backslash inside @@warning.
- Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}'
- (texinfo would also allow \\, but this breaks with PDF output).
+@code{@@ref@{@}} --- link within current manual (type the exact
+node name inside the @code{@{@}}).
@item
-@@ref@{@} - normal references (type the exact node name inside the
-@{@}).
+@code{@@ressay@{@}} --- link to Engraving Essay.
@item
-@@ruser@{@} - link to the NR.
+@code{@@rextend@{@}} --- link to Extending LilyPond.
@item
-@@rlearning@{@} - link to the LM.
+@code{@@rglos@{@}} --- link to the Music Glossary.
@item
-@@rglos@{@} - link to the MG.
+@code{@@rinternals@{@}} --- link to the Internals Reference.
@item
-@@rprogram@{@} - link to the AU.
+@code{@@rlearning@{@}} --- link to Learning Manual.
@item
-@@rlsr@{@} - link to a Snippet section.
+@code{@@rlsr@{@}} --- link to a Snippet section.
@item
-@@rinternals@{@} - link to the IR.
+@code{@@rprogram@{@}} --- link to Application Usage.
@item
-@@uref@{@} - link to an external url.
+@code{@@ruser@{@}} --- link to Notation Reference.
+
+@item
+@code{@@rweb@{@}} --- link to General Informaion.
+
+@item
+@code{@@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: @q{@code{The letter@@tie@{@}@@q@{I@} is skipped}}
+
+@item
+@code{@@uref@{@}} --- link to an external url.
+
+@item
+@code{@@var} --- Use for variables.
+
+@item
+@code{@@version@{@}} --- Return the current LilyPond version
+string.
+
+@item
+@code{@@warning@{@}} --- produces a @qq{Note:@tie{}} box. Use for
+important messages.
@end itemize
@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
+this is, don't say @q{Ba@@ss@{@}tuba} but @q{Baßtuba}. This ensures
that all such characters appear in all output formats.
@end itemize
Application Usage:
@@rprogram@{blah@}.
+Extending LilyPond:
+@@rextend@{frob@}.
+
Installed Files:
@@file@{path/to/dir/blahz@}.
manual.
@item
-@@predefined ... @@endpredefined is for commands in ly/*-init.ly
-FIXME?
+@@predefined ... @@endpredefined is for commands in
+@file{ly/*-init.ly}
@item
Do not include any real info in second-level sections (ie 1.1
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
+where documentation has been built, cd into Documentation and run:
+
+@example
+make check-xrefs
+make fix-xrefs
+@end example
+
+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/.
+@c temporary? how long will kainhofer be used? -gp
+Also of interest may be the linkdoc checks on kainhofer.com. Be
+warned that these docs are not completely rebuilt every day, so it
+might not accurately reflect the current state of the docs.
+
+@example
+@uref{http://kainhofer.com/~lilypond/linkdoc/}
+@end example
+
@node General writing
@subsection General writing
@ref{Adding and editing snippets}.
-@node Updating docs with convert-ly
-@section Updating doc with @command{convert-ly}
+@node Scripts to ease doc work
+@section Scripts to ease doc work
+
+@subheading Stripping whitespace
+
+@c TODO: should this be documented elsewhere? It's useful for
+@c more than just docs.
+To remove extra whitespace from the ends of lines, run
+
+@example
+scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
+@end example
+
+
+@subheading Sectioning commands
+
+@warning{These commands add whitespace.}
+
+The emacs @code{M-x texinfo-all-menus-update} command will
+regenerate @@menu blocks. This can also be run with this
+command-line script:
+
+@example
+#!/bin/sh
+emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
+@end example
+
+@noindent
+(save the above as something like @command{texinfo-menus.sh}, make
+it executable, then run @command{texinfo-menus.sh foo.itely})
+
+
+@subheading Updating doc with @command{convert-ly}
cd into @file{Documentation/} and run
All people interested in LilyPond translations are invited to subscribe
to this list regardless of the amount of their contribution, by sending
an email to @code{translations-request@@lilynet.net} with subject
-@code{subscribe} and an empty message body.
+@code{subscribe} and an empty message body. Unless mentioned explicitly
+or except if a translations coordinator contacts you privately, you
+should send questions, remarks, patches to this list
+@code{translations@@lilynet.net}; especially note that the traffic is so
+high on English-speaking list @code{lilypond-user@@gnu.org} that it may
+take months before your request or contribution is handled if you send a
+email to these lists.
@menu
* Getting started with documentation translation::
@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}.
+First, get the sources of branch @code{lilypond/translation} from the
+Git repository, see @ref{Starting with Git}.
@menu
* Translation requirements::
@node Which documentation can be translated
@unnumberedsubsubsec Which documentation can be translated
-FIXME: take into account the new web site integration in main sources.
-
The makefiles and scripts infrastructure currently supports translation
of the following documentation:
@itemize
-@item documentation index (HTML);
-@item the Learning Manual, the Notation Reference and Application Usage
--- Texinfo source, PDF and HTML output; Info output might be added if
-there is enough demand for it;
+@item the web site, the Learning Manual, the Notation Reference and
+Application Usage -- Texinfo source, PDF and HTML output; Info output
+might be added if there is enough demand for it;
@item the Changes document.
@end itemize
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
@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::
+* Translating the Web site and other Texinfo documentation::
+* Adding a Texinfo manual::
@end menu
@node Files to be translated
@include contributor/doc-translation-list.itexi
-@node Translating the Learning Manual and other Texinfo documentation
-@unnumberedsubsubsec Translating the Learning Manual and other Texinfo documentation
-
-@iftex
-@vskip 12pt
-@end iftex
-@cartouche
-@b{Note:} node names and section titles are now translated directly in
-Texinfo source files. In case you have files in your working tree that
-have not been converted, please pull first, then run
-
-@example
-make -C Documentation/po doc
-export LYDOC_LOCALEDIR=Documentation/po/out-www
-export PYTHONPATH=python:python/auxiliar
-scripts/auxiliar/tely-gettext.py @var{manual.tely}
-@end example
+In addition, not listed above, Snippets' titles and descriptions
+should be translated; they are a part of the Notation Reference and
+therefore their priority is 5.
-@noindent
-This will also update files included in @file{@var{manual}.tely}, and of
-course this script can be used for individual @file{@var{foo}.itely}
-files too.
-@end cartouche
+@node Translating the Web site and other Texinfo documentation
+@unnumberedsubsubsec Translating the Web site and other Texinfo documentation
Every piece of text should be translated in the source file, except
Texinfo comments, text in @code{@@lilypond} blocks and a few cases
@@@var{section_commmand} @@translationof} trio mentioned above) in the
expected source file and define all its parent nodes; for each node you
have defined this way but have not translated, insert a line that
-contains @code{@@untranslated} and append @code{ @@c external} to the
-line that contains @code{@@translationof}. That is, you should end up
+contains @code{@@untranslated}. That is, you should end up
for each untranslated node with something like
@example
@@node @var{translation of Foo bar}
@@@var{section_command} @var{translation of Bar baz}
-@@translationof Foo bar @@c external
+@@translationof Foo bar
@@untranslated
@end example
+@warning{you do not have to translate the node name of a cross-reference
+to a node that you do not have translated. If you do, you must define
+an @qq{empty} node like explained just above; this will produce a
+cross-reference with the translated node name in output, although the
+target node will still be in English. On the opposite, if all
+cross-references that refer to an untranslated node use the node name in
+English, then you do not have to define such an @qq{empty} node, and the
+cross-reference text will appear in English in the output. The choice
+between these two strategies implies its particular maintenance
+requirements and is left to the translators, although the opinion of the
+Translation meister leans towards not translating these
+cross-references.}
+
+Please think of the fact that it may not make sense translating
+everything in some Texinfo files, and you may take distance from the
+original text; for instance, in the translation of the web site section
+Community, you may take this into account depending on what you know the
+community in your language is willing to support, which is possible only
+if you personnally assume this support, or there exists a public forum
+or mailing list listed in Community for LilyPond in your language:
+
+@itemize
+@item @rweb{Bug reports}: this page should be translated only if you
+know that every bug report sent on your language's mailing list or forum
+will be handled by someone who will translate it to English and send it
+on bug-lilypond or add an issue in the tracker, then translate back the
+reply from developers.
+
+@item @rweb{Help us}: this page should be translated very freely,
+and possibly not at all: ask help for contributing to LilyPond for tasks
+that LilyPond community in your language is able and going to handle.
+@end itemize
+
@noindent
+In any case, please mark in your work the sections which do not result
+from the direct translation of a piece of English translation, using
+comments i.e. lines starting with @q{@code{@@c}}.
+
Finally, press in Emacs @key{C-c C-u C-a} to update or generate
menus. This process should be made easier in the future, when the helper
script @command{texi-langutils.py} and the makefile target are updated.
Take care of using typographic rules for your language, especially in
@file{macros.itexi}.
+If you wonder whether a word, phrase or larger piece of text should be
+translated, whether it is an argument of a Texinfo command or a small
+piece sandwiched between two Texinfo commands, try to track whether and
+where it appears in PDF and/or HTML output as visible text. This piece
+of advice is especially useful for translating @file{macros.itexi}.
Please keep verbatim copies of music snippets (in @code{@@lilypond}
blocs). However, some music snippets containing text that shows in
@file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
and editing snippets}.
-@code{@@example} blocs need not be verbatim copies, e.g. variable
+@code{@@example} blocks need not be verbatim copies, e.g. variable
names, file names and comments should be translated.
Finally, please carefully apply every rule exposed in @ref{Texinfo
list.
-@node Translating the Notation Reference and Application Usage
-@unnumberedsubsubsec Translating the Notation Reference and Application Usage
+@node Adding a Texinfo manual
+@unnumberedsubsubsec Adding a Texinfo manual
-Copy @file{notation.tely} (or @file{application.tely},
-respectively) into @file{@var{MY-LANGUAGE}}, 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.
+In order to start translating a new manual whose basename is @var{FOO},
+do
+@example
+cd Documentation/@var{MY-LANGUAGE}
+cp ../@var{FOO}.tely .
+mkdir @var{FOO}
+cp web/GNUmakefile @var{FOO}
+@end example
-@node Translating the Documentation index index.html.in
-@unnumberedsubsubsec Translating the Documentation index @file{index.html.in}
+@noindent
+then append @var{FOO} to variable @code{SUBDIRS} in
+Documentation/@var{MY-LANGUAGE}/GNUmakefile, then translate file
+@var{MY-LANGUAGE}/@var{FOO}.tely and run @code{skeleton-update}:
-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.
+@example
+cd Documentation/
+make ISOLANG=@var{MY-LANGUAGE} TEXI_LANGUTIL_FLAGS=--head-only skeleton-update
+@end example
+
+@noindent
+Your are now ready to translate the new manual exactly like the web site
+or the Learning Manual.
@node Documentation translation maintenance
easier. These helper scripts make use of the power of Git, the
version control system used for LilyPond development.
+You should use them whenever you would like to update the translation in
+your language, which you may do at the frequency that fits your and your
+cotranslators' respective available times. In the case your translation
+is up-do-date (which you can discover in the first subsection below), it
+is enough to check its state every one or two weeks. If you feel
+overwhelmed by the quantity of documentation to be updated, see
+@ref{Maintaining without updating translations}.
+
@menu
* Check state of translation::
* Updating documentation translation::
+* Updating translation committishes::
@end menu
+@macro seeCommittishesUpdate{}
+@warning{do not forget to update the committish in each file you have
+completely updated, see @ref{Updating translation committishes}.}
+@end macro
+
@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
+First pull from Git -- see @ref{Pulling and rebasing}, but DO NOT rebase
+unless you are sure to master the translation state checking and
+updating system -- then cd into @file{Documentation/} (or at top of the
+source tree, replace @command{make} with @command{make -C
Documentation}) and run
@example
@noindent
In case this file has been renamed since you last updated the
-translation, you should specify both old and new file names,
-e.g. @code{CHECKED_FILES=@var{MY_LANGUAGE}/@{@var{manual},user@}/@var{foo}.itely}.
+translation, you should specify both old and new file names, e.g.
+@code{CHECKED_FILES=@var{MY_LANGUAGE}/@{@var{manual},user@}/@var{foo}.itely}.
To see only which files need to be updated, do
make ISOLANG=@var{MY_LANGUAGE} NO_COLOR=1 check-translation
@end example
+You can see the diffs generated by the commands above as changes that
+you should make in your language to the existing translation, in order
+to make your translation up to date.
+
+@seeCommittishesUpdate
+
+@warning{translation status generation is currently broken, so
+translation status pages have been removed; it will be regenerated again
+as soon as possible, in Texinfo format.}
+
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
diff cannot be generated or is bigger than the file in English itself,
the full file in English will be opened instead.
+@seeCommittishesUpdate
+
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/}
+containing only the first node of the original file in English 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
@ref{Adding and editing snippets}.
+@node Updating translation committishes
+@unnumberedsubsubsec Updating translation committishes
+
+At the beginning of each translated file except PO files, there is a
+committish which represents the revision of the sources which you have
+used to translate this file from the file in English.
+
+When you have pulled and updated a translation, it is very important to
+update this committish in the files you have completely updated (and
+only these); to do this, first commit possible changes to any
+documentation in English which you are sure to have done in your
+translation as well, then replace in the up-to-date translated files the
+old committish by the committish of latest commit, which can be obtained
+by doing
+
+@example
+git rev-list HEAD |head -1
+@end example
+
+A special case is updating Snippet documentation strings in
+@file{Documentation/@var{MY-LANGUAGE}/texidocs}. For these to be
+correctly marked as up-to-date, first run @code{makelsr.py} as
+explained in @ref{Adding and editing snippets}, and commit the
+resulting compiled snippets left in @file{Documentation/snippets/}.
+Say the SHA1 ID code of this commit is <C>. Now edit again your
+translated files in @file{Documentation/@var{MY-LANGUAGE}/texidocs}
+adjusting the 40-digit committish that appears in the text to be <C>;
+finally, commit these updated files. Not doing so would result in
+changes made both to your updates and original snippets to
+persistently appear in the check-translation output as if they were
+out of sync.
+
+This two-phase mechanism avoids the (practically) unsolvable problem
+of guessing what committish will have our update, and pretending to
+put this very committish on the files in the same commit.
+
+@c http://lists.gnu.org/archive/html/lilypond-devel/2009-01/msg00245.html
+@c contains a helper script which could be used to perform massive
+@c committish updates.
+
+
+@seealso
+@ref{LSR work}.
+
+
@node Translations management policies
@subsection Translations management policies
projects / lilypond.git / blobdiff