@node Documentation work
@chapter Documentation work
+There are currently 11 manuals for LilyPond, not including the
+translations. Each book is available in HTML, PDF, and info. The
+documentation is written in a language called @code{texinfo} --
+this allows us to generate different output formats from a single
+set of source files.
+
+To organize multiple authors working on the documentation, we use a
+Version Control System (VCS) called git, previously discussed in
+@ref{Starting with Git}.
+
@menu
* Introduction to documentation work::
* Documentation suggestions::
* 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
they also stem from attempting to find the most effective use of
limited documentation help.
+Before undertaking any large documentation work, contributors are
+encouraged to contact the @ref{Meisters, Documentation Meister}.
+
@node Documentation suggestions
@section Documentation suggestions
@enumerate
@item
-Tell us where the addition should be placed. Please include both
+Tell us where the addition should be placed. Please include both
the section number and title (i.e. "LM 2.13 Printing lyrics").
@item
@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
+take care of the technical details. Here is an example of a
perfect documentation report:
@verbatim
@subheading Larger contributions
To replace large sections of the documentation, the guidelines are
-stricter. We cannot remove parts of the current documentation
+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;
+Ask on the lilypond-devel mailing list if such a rewrite is necessary;
somebody else might already be working on this issue!
@item
@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
+lilypond-devel with your documentation submissions. Unfortunately
+there is a strict “no top-posting” check on the mailing list; to avoid
this, add:
> I'm not top posting.
@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
+All manuals live in @file{Documentation/}.
+
+In particular, there are four user manuals, their respective master
+source files are @file{learning@/.tely} (LM, Learning Manual),
+@file{notation@/.tely} (NR, Notation Reference),
+@file{music@/-glossary@/.tely} (MG, Music Glossary), 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, located in a subdirectory
+associated to the manual (@file{learning/} for @file{learning@/.tely}, and
+so on); list the subdirectory of 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}.
+Developer manuals live in @file{Documentation/} too. Currently there is
+only one: the Contributor's Guide @file{contrib@/-guide@/.texi} you are
+reading.
-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}.
+Snippet files are part of documentation, and the Snippet List (SL) lives
+in @file{Documentation/} just like the manuals. For information about
+how to modify the snippet files and SL, see @ref{LSR work}.
@node Sectioning commands
@itemize
@item
-Please leave two blank lines above a @@node; this makes it
+Please leave two blank lines above a @code{@@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.
+Do not use any @code{@@} commands for a @code{@@node}. They may be
+used for any @code{@@sub...} sections or headings however.
+
+@example
+not:
+@@node @@code@{Foo@} Bar
+@@subsection @@code@{Foo@} Bar
+
+but instead:
+@@node Foo Bar
+@@subsection @@code@{Foo@} Bar
+@end example
+
+@item
+If a heading is desired without creating a @code{@@node}, please use
+the following:
+
+@example
+@@subheading Foo
+@end example
+
+@item
+Sectioning commands (@code{@@node} and @code{@@section}) must not appear
+inside an @code{@@ignore}. Separate those commands with a space, ie
+@code{@@n}@tie{}@code{ode}.
@end itemize
+Nodes must be included inside a
+
+@example
+@@menu
+* foo::
+* bar::
+@@end menu
+@end example
+
+@noindent
+construct. These are easily constructed with automatic tools; see
+@ref{Scripts to ease doc work}.
+
@node LilyPond formatting
@subsection LilyPond formatting
@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"}
+Use two spaces for indentation in lilypond examples (no tabs).
@item
All engravers should have double-quotes around them:
\consists "Spans_arpeggio_engraver"
@end example
-Again, LilyPond does not strictly require this, but it is a useful
-standard to follow.
+LilyPond does not strictly require this, but it is a useful
+convention to follow.
@item
-Examples should end with a complete bar if possible.
+All context or layout object strings should be prefaced with @code{#}.
+Again, LilyPond does not strictly require this, but it is helpful
+to get users accustomed to this scheme construct, i.e. @code{\set
+Staff.instrumentName = #"cello"}
@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:
+Try to avoid using @code{#'} or @code{#`} within when describing
+context or layout properties outside of an @code{@@example} or @code{@@lilypond}, unless
+the description explicitly requires it.
-@example
-\override textscript #'padding = #3 c1^"hi"
-@end example
+i.e. @qq{...setting the @code{transparent} property leaves the object where it
+is, but makes it invisible.}
-Good:
+@item
+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
+Tweaks should, if possible, also occur on their own line.
@example
-\override textscript #'padding = #3
-c1^"hi"
+not: \override TextScript #'padding = #3 c1^"hi"
+but instead: \override TextScript #'padding = #3
+ c1^"hi"
@end example
@item
@@lilypond[verbatim,quote,relative=1]
@end example
-If you want to use \layout@{@} or define variables, use
+If you want to use @code{\layout@{@}} or define variables, use
@example
@@lilypond[verbatim,quote]
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.
the line(s) to which they refer.
@item
-Add extra spaces around @{ @} marks; ie
+For clarity, always use @{ @} marks even if they are not technically
+required; i.e.
+
+@example
+not:
+
+\context Voice \repeat unfold 2 \relative c' @{
+ c2 d
+@}
+
+but instead:
+
+\context Voice @{
+ \repeat unfold 2 @{
+ \relative c' @{
+ c2 d
+ @}
+ @}
+@}
+@end example
+
+@item
+Add a space around @{ @} marks; i.e.
@example
-not: \chordmode @{c e g@}
+not: \chordmode@{c e g@}
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.
+Use @{ @} marks for additional @code{\markup} format commands; i.e.
+
+@example
+not: c^\markup \tiny\sharp
+but instead: c^\markup @{ \tiny \sharp @}
+@end example
+
+@item
+Remove any space around @code{<} @code{>} marks; i.e.
+
+@example
+not: < c e g > 4
+but instead: <c e g>4
+@end example
+
+@item
+Beam, slur and tie marks should begin immediately after the first
+note with beam and phrase marks ending immediately after the last.
+
+@example
+a8(\ ais16[ b cis( d] b) cis4~ b' cis,\)
+@end example
@item
If you want to work on an example outside of the manual (for
@example
\paper @{
- #(define dump-extents #t)
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
ragged-right = ##t
@end example
You may not change any of these values. If you are making an
-example demonstrating special \paper@{@} values, contact the
+example demonstrating special @code{\paper@{@}} values, contact the
Documentation Editor.
@end itemize
@subsection Text formatting
@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). Also see the recommendations for fixed-width
+fonts in the @ref{Syntax survey}.
@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 @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}.
+@end itemize
+
+
+@node Syntax survey
+@subsection Syntax survey
+
+
+@menu
+* Comments::
+* Cross references::
+* External links::
+* Fixed-width font::
+* Indexing::
+* Lists::
+* Special characters::
+* Miscellany::
+@end menu
+
+
+@node Comments
+@unnumberedsubsubsec Comments
+@itemize
@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.
+@code{@@c @dots{}} --- single line comment. @samp{@@c NOTE:} is a
+comment which should remain in the final version. (gp only
+command ;)
@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:
+@code{@@ignore} --- multi-line comment:
@example
-The variable@@tie@{@}@@var@{a@} ...
+@@ignore
+@dots{}
+@@end ignore
@end example
+@end itemize
+
+
+@node Cross references
+@unnumberedsubsubsec Cross references
+
+Enter the exact @code{@@node} name of the target reference between
+the brackets (eg.@tie{}@w{@samp{@@ref@{Syntax survey@}}}). Do not
+split a cross-reference across two lines -- this causes the
+cross-reference to be rendered incorrectly in html documents.
+
+@itemize
+@item
+@code{@@ref@{@dots{}@}} --- link within current manual.
+
+@item
+@code{@@rchanges@{@dots{}@}} --- link to Changes.
@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
+@code{@@rcontrib@{@dots{}@}} --- link to Contributor's Guide.
+
+@item
+@code{@@ressay@{@dots{}@}} --- link to Engraving Essay.
+
+@item
+@code{@@rextend@{@dots{}@}} --- link to Extending LilyPond.
+
+@item
+@code{@@rglos@{@dots{}@}} --- link to the Music Glossary.
+
+@item
+@code{@@rinternals@{@dots{}@}} --- link to the Internals Reference.
+
+@item
+@code{@@rlearning@{@dots{}@}} --- link to Learning Manual.
+
+@item
+@code{@@rlsr@{@dots{}@}} --- link to a Snippet section.
+
+@item
+@code{@@rprogram@{@dots{}@}} --- link to Application Usage.
+
+@item
+@code{@@ruser@{@dots{}@}} --- link to Notation Reference.
+
+@item
+@code{@@rweb@{@dots{}@}} --- link to General Information.
+@end itemize
+
+
+@node External links
+@unnumberedsubsubsec External links
+
+@itemize
+@item
+@code{@@email@{@dots{}@}} --- create a @code{mailto:} E-mail link.
+
+@item
+@code{@@uref@{@var{URL}[, @var{link text}]@}} --- link to an
+external url. Use within an @code{@@example ... @@end example}.
@example
@@example
- foo @{
- bar
- @}
+@@uref@{URL [, link text ]@}
@@end example
@end example
+@end itemize
-@noindent
-should be replaced with
+
+@node Fixed-width font
+@unnumberedsubsubsec Fixed-width font
+
+@itemize
+@item
+@code{@@code@{@dots{}@}}, @code{@@samp@{@dots{}@}} ---
+
+Use the @code{@@code@{@dots{}@}} command for individual
+language-specific tokens (keywords, commands, engravers, scheme
+symbols, etc.). Ideally, a single @code{@@code@{@dots{}@}} block
+should fit within one line in the PDF output. Use the
+@code{@@samp@{@dots{}@}} command when you have a short example of
+user input, unless it constitutes an entire @code{@@item} by
+itself, in which case @code{@@code@{@dots{}@}} is preferable.
+Otherwise, both should only be used when part of a larger sentence
+within a paragraph or @code{@@item}. Never use a
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} block as a
+free-standing paragraph; use @code{@@example} instead.
+
+A single unindented line in the PDF has space for about 79
+fixed-width characters (76 if indented). Within an @code{@@item}
+there is space for about 75 fixed-width characters. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+
+However, even short blocks of @code{@@code@{@dots{}@}} and
+@code{@@samp@{@dots{}@}} can run into the margin if the Texinfo
+line-breaking algorithm gets confused. Additionally, blocks that
+are longer than this may in fact print nicely; it all depends
+where the line breaks end up. If you compile the docs yourself,
+check the PDF output to make sure the line breaks are
+satisfactory.
+
+The Texinfo setting @code{@@allowcodebreaks} is set to
+@code{false} in the manuals, so lines within
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} blocks will
+only break at spaces, not at hyphens or underscores. If the block
+contains spaces, use @code{@@w@{@@code@{@dots{}@}@}} or
+@code{@@w@{@@samp@{@dots{}@}@}} to prevent unexpected line breaks.
+
+The Texinfo settings @code{txicodequoteundirected} and
+@code{txicodequotebacktick} are both set in the manuals, so
+backticks (@code{`}) and apostrophes (@code{'}) placed within
+blocks of @code{@@code}, @code{@@example}, or @code{@@verbatim}
+are not converted to left- and right-angled quotes
+(@code{@quoteleft{} @quoteright{}}) as they normally are within
+the text, so the apostrophes in
+@q{@w{@code{@@w@{@@code@{@bs{}relative c''@}@}}}} will display
+correctly. However, these settings do not affect the PDF output
+for anything within a @code{@@samp} block (even if it includes a
+nested @code{@@code} block), so entering
+@q{@code{@@w@{@@samp@{@bs{}relative c''@}@}}} wrongly produces
+@q{@w{@code{@bs{}relative c@quoteright{}@quoteright{}}}} in PDF.
+Consequently, if you want to use a @code{@@samp@{@dots{}@}} block
+which contains backticks or apostrophes, you should instead use
+@q{@code{@@q@{@@code@{@dots{}@}@}}} (or
+@q{@code{@@q@{@@w@{@@code@{@dots{}@}@}@}}} if the block also
+contains spaces). Note that backslashes within
+@code{@@q@{@dots{}@}} blocks must be entered as @samp{@@bs@{@}},
+so the example above would be coded as
+@q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
+
+@item
+@code{@@command@{@dots{}@}} --- Use for command-line commands (eg.
+@samp{@@command@{lilypond-book@}}).
+
+@item
+@code{@@example} --- Use for examples of program code. Do not add
+extraneous indentation (i.e. don't start every line with
+whitespace). Use the following layout (notice the use of blank
+lines). Omit the @code{@@noindent} if the text following the
+example starts a new paragraph:
@example
+@var{@dots{}text leading into the example@dots{}}
+
@@example
-foo @{
- bar
-@}
+@dots{}
@@end example
+
+@@noindent
+@var{continuation of the text@dots{}}
@end example
-@noindent
-where `@@example' starts the line (without leading spaces).
+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}, individual lines in the
+@code{@@example} block should not exceed 70 columns. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+
+For long 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 @samp{@@smallexample
+@dots{} @@end@tie{}smallexample} instead, which uses a smaller
+fontsize. Use @code{@@example} whenever possible, but if needed,
+@code{@@smallexample} can fit up to 90 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 compress the input vertically; this is, do not use
+@code{@@file@{@dots{}@}} --- Use for filenames and directories.
-@example
- Beginning of logical unit
- @@example
- ...
- @@end example
- continuation of logical unit
-@end example
+@item
+@code{@@option@{@dots{}@}} --- Use for options to command-line
+commands (eg. @samp{@@option@{--format@}}).
-@noindent
-but instead do
+@item
+@code{@@verbatim} --- Prints the block exactly as it appears in
+the source file (including whitespace, etc.). For program code
+examples, use @code{@@example} instead. @code{@@verbatim} uses
+the same format as @code{@@example}.
-@example
-Beginning of logical unit
+Individual lines within an @code{@@verbatim} block should not
+exceed 74 characters; otherwise they will run into the margin in
+the PDF output, and may get clipped. If an @code{@@verbatim}
+block is part of an @code{@@item}, individual lines in the
+@code{@@verbatim} block should not exceed 70 columns. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+@end itemize
-@@example
-...
-@@end example
-@@noindent
-continuation of logical unit
-@end example
+@node Indexing
+@unnumberedsubsubsec Indexing
+
+@itemize
+@item
+@code{@@cindex @dots{}} --- General index. Please add as many as you can.
+Don't capitalize the first word.
+
+@item
+@code{@@funindex @dots{}} --- is for a \lilycommand.
+@end itemize
+
-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.
+@node Lists
+@unnumberedsubsubsec Lists
+@itemize
@item
-in @@itemize use @@item
-on a separate line like this:
+@code{@@enumerate} --- Create an ordered list (with numbers).
+Always put @samp{@@item} on its own line, and separate consecutive
+items with a blank line:
@example
-@@itemize
+@@enumerate
@@item
Foo
@@item
Bar
+@@end enumerate
@end example
-Do not use @@itemize @@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, tere will be an ugly line break in PDF output unless you
-enclose it with
-
-@example
-@@w@{ ... @}
-
- e.g.
-
-@@w@{"@@version@{@}"@}
-@end example
-
+@code{@@itemize} --- Create an unordered list (with bullets). Use
+the same format as @code{@@enumerate}. Do not use
+@samp{@@itemize@tie{}@@bullet}.
@end itemize
-@node Syntax survey
-@subsection Syntax survey
+@node Special characters
+@unnumberedsubsubsec Special characters
@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
+@code{--}, @code{---} --- Create an en dash (--) or an em dash
+(---) in the text. To print two or three literal hyphens in a
+row, wrap one of them in a @code{@@w@{@dots{}@}} (eg.
+@samp{-@@w@{-@}-}).
@item
-@@cindex - General index. Please add as many as you can. Don't
- capitalize the first word.
-@item
-@@funindex - is for a \lilycommand.
+@code{@@@@}, @code{@@@{}, @code{@@@}} --- Create an at-sign (@@),
+a left curly bracket (@{), or a right curly bracket (@}).
@item
-@@example ... @@end ignore - example text that should be set as a
- blockquote. Any @{@} must be escaped with @@@{ @}@@
-@item
-@@itemize @@item
-A @@item
-B ... @@end itemize - for bulleted lists.
- Do not compress vertically like this.
+@code{@@bs@{@}} --- Create a backslash within a
+@code{@@q@{@dots{}@}}, @code{@@qq@{@dots{}@}}, or
+@code{@@warning@{@dots{}@}} block. This is a custom LilyPond
+macro, not a builtin @@-command in Texinfo. Texinfo would also
+allow @samp{\\}, but this breaks the PDF output.
@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.
+@code{@@tie@{@}} --- Create a @emph{variable-width} non-breaking
+space in the text (use @w{@samp{@@w@{ @}}} for a single
+@emph{fixed-width} non-breaking space). 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: @samp{The letter@@tie@{@}@@q@{I@} is
+skipped}
+@end itemize
-@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.
+@node Miscellany
+@unnumberedsubsubsec Miscellany
+@itemize
@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{@@notation@{@dots{}@}} --- refers to pieces of notation, e.g.
+@samp{@@notation@{clef@}}. Also use for specific lyrics
+(@samp{the @@notation@{A@tie{}-@tie{}men@} is centered}).
+Only use once per subsection per term.
@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.
+@code{@@q@{@dots{}@}} --- Single quotes. Used for
+@quoteleft{}vague@quoteright{} terms. To get a backslash
+(\), you must use @samp{@@bs@{@}}.
+
@item
-@@rprogram@{@} - link to the AU.
+@code{@@qq@{@dots{}@}} --- Double quotes. Used for actual quotes
+(@qq{he said}) or for introducing special input modes. To get a
+backslash (\), you must use @samp{@@bs@{@}}.
+
@item
-@@rlsr@{@} - link to a Snippet section.
+@code{@@var@{@dots{}@}} --- Use for variables.
+
@item
-@@rinternals@{@} - link to the IR.
+@code{@@version@{@}} --- Return the current LilyPond version
+string. Use @samp{@@w@{@@version@{@}@}} if it's at the end of a
+line (to prevent an ugly line break in PDF); use
+@samp{@@w@{"@@version@{@}"@}} if you need it in quotes.
+
@item
-@@uref@{@} - link to an external url.
+@code{@@w@{@dots{}@}} --- Do not allow any line breaks.
+@item
+@code{@@warning@{@dots{}@}} --- produces a @qq{Note:@tie{}} box.
+Use for important messages. To get a backslash (\), you must use
+@samp{@@bs@{@}}.
@end itemize
-
@node Other text concerns
@subsection Other text concerns
@itemize
-
@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.
+information see the
+@uref{http://www.gnu.org/software/texinfo/manual/texinfo/,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 @code{@@seealso} section at the bottom.
@item
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,')
+. (i.e. finish the previous sentence/paragraph)
+: (i.e. `in this example:')
+, (i.e. `may add foo with the blah construct,')
@end example
-The old "sentence runs directly into the example" method is not
+The old @qq{sentence runs directly into the example} method is not
allowed any more.
@item
Colon usage
@enumerate
-
@item
To introduce lists
@item
-When beginning a quote: "So, he said,...".
+When beginning a quote: @qq{So, he said,...}.
This usage is rarer. Americans often just use a comma.
@item
When adding a defining example at the end of a sentence.
-
@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.
-
+this is, don't say @samp{Ba@@ss@{@}tuba} but @samp{Baßtuba}. This
+ensures that all such characters appear in all output formats.
@end itemize
-
-
@node Documentation policy
@section Documentation policy
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
+Do not include any real info in second-level sections (i.e. 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).
+(i.e. 1.1.1 Writing Pitches).
@end itemize
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
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
+tweaks for users@dots{} 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.
the difficulty.
@seealso
-
@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 Building only one section of the documentation
+
+In order to save build time, a script is available to build only
+one section of the documentation in English with a default html
+appearance.
+
+The script is available as:
-cd into Documentation and run
+@example
+scripts/auxiliar/doc-section.sh
+@end example
+
+This script will require customization for your site if your
+LilyPond git repository is anyplace but @code{$HOME/lilypond}.
+
+Assuming that no customization is required, you can setup the
+single section build with:
+
+@example
+mkdir $HOME/lilypond/tempdocs
+cp $HOME/lilypond/Documentation/out/version.itexi $HOME/lilypond/tempdocs
+@end example
+
+You can then build a section of the documentation with:
+
+@example
+scripts/auxiliar/doc-section.sh MANUAL SECTION
+@end example
+
+@noindent
+where @code{SECTION} is the name of the file containing the section
+to be build, and @code{MANUAL} isc replaced by the name of the directory
+containing the section. So, for example, to build section 1.1 of the
+Notation Reference, use the command:
+
+@example
+scripts/auxiliar/doc-section.sh notation pitches
+@end example
+
+This script will not work for building sections of the
+Contributors' guide. For building sections of the Contributors'
+Guide, use:
+
+@example
+scripts/auxiliar/cg-section.sh SECTION
+@end example
+
+@noindent
+where @code{SECTION} is the name of the file containing the sections
+to be built. For example, to build section 4 of the Contributors' guide,
+use:
+
+@example
+scripts/auxiliar/cg-section.sh doc-work
+@end example
+
+Like @code{doc-section.sh}, @code{cg-section.sh} may need to be customized
+for your installation.
+
+@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
@example
find . -name '*.itely' | xargs convert-ly -e
+@node Docstrings in scheme
+@section Docstrings in scheme
+
+Material in the Internals reference is generated automatically
+from our source code. Any doc work on Internals therefore
+requires modifying files in @file{scm/@/*.scm}. Texinfo is allowed
+in these docstrings.
+
+Most documentation writers never touch these, though. If you want
+to work on them, please ask for help.
+
+
@node Translating the documentation
@section Translating the documentation
+The mailing list @code{translations@@lilynet.net} is dedicated to
+LilyPond web site and documentation translation; on this list, you will
+get support from the Translations Meister and experienced translators,
+and we regularly discuss translation issues common to all languages.
+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. Unless mentioned explicitly,
+or except if a translations coordinator contacts you privately, you
+should send questions, remarks and patches to the list
+@code{translations@@lilynet.net}. Please note that traffic is high
+on the English-speaking list @code{lilypond-user@@gnu.org}, so it may
+take some time before your request or contribution is handled.
+
@menu
* Getting started with documentation translation::
* Documentation translation details::
* Documentation translation maintenance::
* Translations management policies::
* Technical background::
-* Translation status::
@end menu
@node Getting started with documentation translation
@subsection Getting started with documentation translation
-First, get the sources from the Git repository, see @ref{Documentation
-translations source code}.
+First, get the sources of branch @code{lilypond/translation} from the
+Git repository, see @ref{Starting with Git}.
@menu
* Translation requirements::
@itemize
@item Python 2.4 or higher,
@item GNU Make,
-@item Gettext.
+@item Gettext,
+@item Git.
@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}.
+more quickly; if you are interested, see @ref{Compiling}.
+
+Before undertaking any large translation work, contributors are
+encouraged to contact the @ref{Meisters, Translation Meister}.
-@menu
-@end menu
@node Which documentation can be translated
@unnumberedsubsubsec Which documentation can be translated
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.
+@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
-The following pieces of documentation should be added soon, by
-descending order of priority:
+Support for translating the following pieces of documentation should be
+added soon, by decreasing 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
all dependencies and rerun @command{./configure} (with the same
options as for @command{autogen.sh}).
-Then @command{cd} into @file{Documentation} and run
+Then @command{cd} into @file{Documentation/} and run
@example
make ISOLANG=@var{MY-LANGUAGE} new-lang
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}.
+@file{python/@/langdefs@/.py}.
@node 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
+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.
+
+@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
+mentioned below.
-Any title which comes with one of the following commands must not be
-translated directly in the Texinfo source
+Node names are translated, but the original node name in English should
+be kept as the argument of @code{@@translationof} put after the section
+title; that is, every piece in the original file like
@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
+@@node Foo bar
+@@@var{section_command} Bar baz
@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.
+@noindent
+should be translated as
-@code{@@uref}'s names are to be translated.
+@example
+@@node @var{translation of Foo bar}
+@@@var{section_command} @var{translation of Bar baz}
+@@translationof Foo bar
+@end example
-In any section which looks like
+The argument of @code{@@rglos} commands and the first argument of
+@code{@@rglosnamed} commands must not be translated, as it is the node
+name of an entry in Music Glossary.
+
+Every time you translate a node name in a cross-reference, i.e. the
+argument of commands @code{@@ref, @@rprogram, @@rlearning, @@rlsr,
+@@ruser} or the first argument of their @code{@var{*}named} variants,
+you should make sure the target node is defined in the correct source
+file; if you do not intend to translate the target node right now, you
+should at least write the node definition (that is, the @code{@@node
+@@@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}. That is, you should end up
+for each untranslated node with something like
@example
-@@menu
-* @var{node1}:: @var{thing1}
-* @var{node2}:: @var{thing2}
-...
-@@end menu
+@@node @var{translation of Foo bar}
+@@@var{section_command} @var{translation of Bar baz}
+@@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 personally 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
-the node names @var{nodeN} are @emph{not} to be translated, whereas
-extra title information @var{thingN} is.
+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.
-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.
+Some pieces of text manipulated by build scripts that appear in the
+output are translated in a @file{.po} file -- just like 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}.
+@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
@end example
@noindent
-in the source, open @file{input/lsr/@var{filename}.ly}, translate the
-@code{texidoc} header field it contains, enclose it with
+in the source, open @file{Documentation/@/snippets/@/@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
+@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs/@/@var{filename}@/.texidoc}.
+Additionally, 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{Documentation/@/@var{MY-LANGUAGE}/@/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.
+@noindent
+Then, you should get these translated strings into compiled snippets in
+@file{Documentation/@/snippets}, see @q{General guidelines} in @ref{Adding
+and editing snippets}.
-Index entries (@code{@@cindex} and so on) should be translated.
+@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
-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}.
+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 on @email{translations@@lilynet.net} list
+and/or the Documentation Editors on @email{lilypond-devel@@gnu.org}
+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{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.
+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
@file{Documentation/} and run
@example
-make CHECKED_FILES=@var{MY_LANGUAGE/user/foo.itely} check-translation
+make CHECKED_FILES=@var{MY_LANGUAGE}/@var{manual}/@var{foo}.itely check-translation
@end 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}.
+
To see only which files need to be updated, do
@example
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
+
Global state of the translation is recorded in
-@file{Documentation/translations.html.in}, which is used to generate
+@file{Documentation/@/translations@/.itexi}, which is used to generate
Translations status page. To update that page, do from
@file{Documentation/}
make translation-status
@end example
-This will also leave @file{out/translations-status.txt}, which contains
+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
make ISOLANG=@var{MY_LANGUAGE} update-translation
@end example
+@noindent
or to update a single file
@example
-make CHECKED_FILES=@var{MY_LANGUAGE/user/foo.itely} update-translation
+make CHECKED_FILES=@var{MY_LANGUAGE/@var{manual}/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.
+For each file to be updated, @code{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.
+
+@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
@end example
-@file{.po} message catalogs in @file{Documentation/po/} may be updated
-by issuing from @file{Documentation/} or @file{Documentation/po/}
+@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
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
+@file{@var{MY_LANGUAGE/@/foo/@/every@/.itely}} with music snippets from
+@file{@var{foo/@/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
don't do so, some @code{@@lilypond} snippets might be broken or make
no sense in their context.
+When you have updated texidocs in
+@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}, you can get these
+changes into compiled snippets in @file{Documentation/@/snippets}, see
+@q{General guidelines} in @ref{Adding and editing snippets}.
+
Finally, a command runs the three update processes above for all
enabled languages (from @file{Documentation/}):
@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.
+useful until translations are stabilized after the end of GDP and GOP.
@seealso
+@ref{Maintaining without updating translations},
+@ref{Adding and editing snippets}.
-@ref{Maintaining without updating translations}.
+@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
@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.
+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,
+translators may be --- and that is a very good thing --- involved in
+these projects 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.
+it is possible --- and even recommended --- to perform some maintenance
+that keeps translated documentation usable and eases future translation
+updating. The rationale below the tasks list motivates this plan.
The following tasks are listed in decreasing priority order.
no longer uses this macro.
@item Update @file{*.tely} files completely with
-@command{make check-translation} -- you may want to redirect ouptput
+@command{make check-translation} -- you may want to redirect output
to a file because of overwhelming output, or call check-translation.py
on individual files, see @ref{Check state of translation}.
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
+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.
+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
+Texinfo file in a new buffer @code{*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.
+(e.g. the translated file), copy @code{*Occur*} contents into
+@code{*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
@end example
@noindent
-and then obtain the structure in the *Occur* buffer with @key{C-c s}.
+and then obtain the structure in the @code{*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
+file, just do @key{C-c C-u C-a} (@qq{update all menus}) when you have
updated all the rest of the file.
@item Moving to next or previous node using incremental search: press
@end example
@noindent
-This step requires a sucessful documentation build (with @command{make
+This step requires a successful 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
@item @code{lilypond/translation} Git branch may be merged into
master only if LilyPond (@command{make all}) and documentation
-(@command{make doc}) compile succesfully.
+(@command{make doc}) compile successfully.
@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
+doc} are successful (in order to ease documentation compilation by
translators), or when significant changes had been made in
documentation in English in master branch.
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/}.
+are located in @file{scripts/@/auxiliar/}.
@itemize
@item @file{check_translation.py} -- show diff to update a translation,
"makeinfo --html" has been dropped.
@end itemize
-Other scripts are used in the build process, in @file{scripts/build/}:
+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/}:
+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
+@item @file{postprocess_html.py} (module imported by @file{www_post@/.py}) -- add footer and
tweak links in HTML pages.
@end itemize
@itemize
@item @file{python/langdefs.py} -- language definitions module
@end itemize
-
-
-@node Translation status
-@subsection Translation status
-
-
projects / lilypond.git / blobdiff