@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
-perfect documentation report:
+take care of the technical details.
+
+@item
+Send the suggestions to the @code{bug-lilypond} mailing list as
+discussed in @rweb{Contact}.
+
+@item
+Here is an example of a perfect documentation report:
@verbatim
-To: lilypond-devel@gnu.org
+To: bug-lilypond@gnu.org
From: helpful-user@example.net
Subject: doc addition
@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
@end enumerate
+@subheading Contributions that contain examples using overrides
+
+Examples that use overrides, tweaks, customer Scheme functions etc. are
+(with very few exceptions) not included in the main text of the manuals;
+as there would be far too many, equally useful, candidates.
+
+The correct way is to submit your example, with appropriate explanatory
+text and tags, to the LilyPond Snippet Repository (LSR). Snippets that
+have the @qq{docs} tag can then be easily added as a
+@emph{selected snippet} in the documentation. It will also appear
+automatically in the Snippets lists. See @ref{Introduction to LSR}.
+
+Snippets that @emph{don't} have the @qq{docs} tage will still be
+searchable and viewable within the LSR, but will be not be included in
+the Snippets list or be able to be included as part of the main
+documentation.
+
+Generally, any new snippets that have the @qq{docs} tag are more
+carefully checked for syntax and formatting.
+
+@subheading Announcing your snippet
+
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 mailing list; to avoid
+lilypond-devel with your documentation submissions. Unfortunately
+there is a strict @q{no top-posting} check on the mailing list; to avoid
this, add:
-> I'm not top posting.
+@code{> I'm not top posting}
+
+(you must include the > ) to the top of your documentation addition.
-(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.
-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!
+Thanks for your interest!
@node Texinfo introduction and usage policy
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
+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
+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/} too. Currently there is
-only one: the Contributor's 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
@node Sectioning commands
@subsection Sectioning commands
-Most of the manual operates at the
+The Notation Reference uses section headings at four, occasionally
+five, levels.
+
+@itemize
+
+@item Level 1: @@chapter
+@item Level 2: @@section
+@item Level 3: @@subsection
+@item Level 4: @@unnumberedsubsubsec
+@item Level 5: @@subsubsubheading
+@end itemize
+
+The first three levels are numbered in html, the last two are not.
+Numbered sections correspond to a single html page in the split html
+documents.
+
+The first four levels always have accompanying nodes so they can be
+referenced and are also included in the ToC in html.
+
+Most of the manual is written at level 4 under headings created with
@example
@@node Foo
-@@subsubsection Foo
+@@unnumberedsubsubsec Foo
@end example
-@noindent
-level. Sections are created with
+Level 3 subsections are created with
@example
@@node Foo
@end example
@item
-If a heading is desired without creating a @code{@@node}, please use
-the following:
+With the exception of @code{@@} commands, the section name must
+match the node name exactly.
+
+@item
+No commas may be used in the node names.
+
+@item
+If a heading is desired without creating a @code{@@node}, please use:
@example
-@@subheading Foo
+@@subsubsubheading Foo
@end example
@item
@itemize
+@item
+Most LilyPond examples throughout the documentation can be produced
+with:
+
+@example
+@@lilypond[verbatim,quote,relative=1]
+@end example
+
+or
+
+@example
+@@lilypond[verbatim,quote,relative=2]
+@end example
+
+If using any combination of @code{\header@{@}}, @code{\score@{@}} or
+@code{\layout@{@}} in your example, then you must omit the
+@code{relative} variable and either use absolute entry mode or an
+explicit @code{\relative@{@}} construction.
+
+If using @code{\book@{@}} in your example then you must also omit the
+@code{relative} variable and either use absolute entry mode or an
+explicit @code{\relative@{@}} construction. However, you must also
+include the @code{papersize=X} variable, where @code{X} is a defined
+paper size from within @file{scm/paper.scm}. This is to avoid the
+default @code{a4} paper size being used and leaving too much unnecessary
+whitespace and potentially awkward page breaks in the PDFs.
+
+The preferred @code{papersize}s are @code{a5}, @code{a6} or
+@code{a8landscape}.
+
+@code{a8landscape} works best for a single measure with a single title
+and/or single @code{tagline}:
+
+@example
+@@lilypond[papersize=a8landscape,verbatim]
+\book @{
+ \header @{
+ title = "A scale in LilyPond"
+ @}
+ \relative @{
+ c d e f
+ @}
+@}
+@@end lilypond
+@end example
+
+and can also be used to easily show features that require page breaks
+(i.e. page numbers) without taking large amounts of space within the
+documentation. Do not use the @code{quote} option with this paper size.
+
+@code{a5} or @code{a6} paper sizes are best used for examples that have
+more than two measures of music or require multiple staves (i.e. to
+illustrate cross-staff features, RH and LH parts etc.) and where
+@code{\book@{@}} constructions are required or where @code{a8landscape}
+produces an example that is too cramped. Depending on the example the
+@code{quote} option may need to be omitted.
+
+In rare cases, other options may be used (or omitted), but ask first.
+
+@item
+Please avoid using extra spacing either after or within the
+@code{@@lilypond} parameters.
+
+@example
+not: @@lilypond [verbatim, quote, relative=1]
+but instead: @@lilypond[verbatim,quote,relative=1]
+@end example
+
+@item
+Inspirational headwords are produced with:
+
+@example
+@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
+@{pitches-headword.ly@}
+@end example
+
+@item
+LSR snippets are linked with:
+
+@example
+@@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+@{filename.ly@}
+@end example
+
@item
Use two spaces for indentation in lilypond examples (no tabs).
c1^"hi"
@end example
-@item
-Most LilyPond input should be produced with:
-
-@example
-@@lilypond[verbatim,quote,relative=2]
-@end example
-
-@noindent
-or
-
-@example
-@@lilypond[verbatim,quote,relative=1]
-@end example
-
-If you want to use @code{\layout@{@}} or define variables, use
-
-@example
-@@lilypond[verbatim,quote]
-@end example
-
-In rare cases, other options may be used (or omitted), but ask first.
-
-@item
-Inspirational headwords are produced with
-
-@example
-@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-@{pitches-headword.ly@}
-@end example
-
-@item
-LSR snippets are linked with
-
-@example
-@@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-@{filename.ly@}
-@end example
-
@noindent
excepted in Templates, where `doctitle' may be omitted.
@item
Avoid long stretches of input code. Nobody is going to read
-them in print. Create small examples. However, this does not mean
+them in print. Create small examples. However, this does not mean
it has be minimal.
@item
note with beam and phrase marks ending immediately after the last.
@example
-a8(\ ais16[ b cis( d] b) cis4~ b' cis,\)
+a8\( ais16[ b cis( d] b) cis4~ b' cis,\)
@end example
@item
\paper @{
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
- ragged-right = ##t
- force-assignment = #""
line-width = #(- line-width (* mm 3.000000))
@}
@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.
+Use the @code{@@code@{@dots{}@}} command when referring to
+individual language-specific tokens (keywords, commands,
+engravers, scheme symbols, etc.) in the text. 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}. Do not use
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} inside an
+@code{@@example} block, and do not use either 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}
@q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
@item
-@code{@@command@{@dots{}@}} --- Use for command-line commands (eg.
-@samp{@@command@{lilypond-book@}}).
+@code{@@command@{@dots{}@}} --- Use when referring to command-line
+commands within the text (eg. @samp{@@command@{convert-ly@}}). Do
+not use inside an @code{@@example} block.
@item
@code{@@example} --- Use for examples of program code. Do not add
@code{@@smallexample} line by about 5 columns.
@item
-@code{@@file@{@dots{}@}} --- Use for filenames and directories.
+@code{@@file@{@dots{}@}} --- Use when referring to filenames and
+directories in the text. Do not use inside an @code{@@example}
+block.
@item
-@code{@@option@{@dots{}@}} --- Use for options to command-line
-commands (eg. @samp{@@option@{--format@}}).
+@code{@@option@{@dots{}@}} --- Use when referring to command-line
+options in the text (eg. @samp{@@option@{--format@}}). Do not use
+inside an @code{@@example} block.
@item
@code{@@verbatim} --- Prints the block exactly as it appears in
@itemize
@item
@code{@@enumerate} --- Create an ordered list (with numbers).
-Always put @samp{@@item} on its own line, and separate consecutive
-items with a blank line:
+Always put @samp{@@item} on its own line. As an exception, if all
+the items in the list are short enough to fit on single lines, placing
+them on the @samp{@@item} lines is also permissible. @samp{@@item}
+and @samp{@@end@tie{}enumerate} should always be preceded by a blank
+line.
@example
@@enumerate
+
@@item
-Foo
+A long multi-line item like this one must begin
+on a line of its own and all the other items in
+the list must do so too.
@@item
-Bar
+Even short ones
+
+@@end enumerate
+@end example
+
+@example
+@@enumerate
+
+@@item Short item
+
+@@item Short item
+
@@end enumerate
@end example
backslash (\), you must use @samp{@@bs@{@}}.
@item
-@code{@@var@{@dots{}@}} --- Use for variables.
+@code{@@var@{@dots{}@}} --- Use for metasyntactic variables (such
+as @code{@var{foo}}, @code{@var{bar}}, @code{@var{arg1}}, etc.).
+In most cases, when the @code{@@var@{@dots{}@}} command appears in
+the text (and not in an @code{@@example} block) it should be
+wrapped with an appropriate texinfo code-highlighting command
+(such as @code{@@code}, @code{@@samp}, @code{@@file},
+@code{@@command}, etc.). For example:
+@samp{@@code@{@@var@{foo@}@}},
+@samp{@@file@{@@var@{myfile.ly@}@}},
+@w{@samp{@@samp@{git checkout @@var@{branch@}@}}}, etc. This
+improves readability in the PDF and HTML output.
@item
@code{@@version@{@}} --- Return the current LilyPond version
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
+@file{.itely} file. In some cases, tweaks may be placed in the main
text, but ask about this first.
Finally, you should assume that users know what the notation
Application Usage:
@@rprogram@{blah@}.
+Essay on automated music engraving:
+@@ressay@{yadda@}.
+
Extending LilyPond:
@@rextend@{frob@}.
@item
@@predefined ... @@endpredefined is for commands in
-@file{ly/@/*-init@/.ly}
+@file{ly/*-init.ly}
@item
Do not include any real info in second-level sections (i.e. 1.1
but other than that all material goes into third-level sections
(i.e. 1.1.1 Writing Pitches).
+@item
+The @@knownissues should not discuss any issues that are in the
+tracker, unless the issue is Priority-Postponed. The goal is to
+discuss any overall architecture or syntax decisions which may be
+interpreted as bugs. Normal bugs should not be discussed here,
+because we have so many bugs that it would be a huge task to keep
+the @@knownissues current and accurate all the time.
+
@end itemize
@end example
@noindent
-do not bother with the @@code@{@} (they are added automatically).
+Do not bother with the @@code@{@} (they are added automatically).
These items are added to both the command index and the unified
-index.
+index. Both index commands should go in front of the actual material.
-Both index commands should go in front of the actual material.
-
-@@cindex entries should not be capitalized, ie
+@item
+@@cindex entries should not be capitalized, i.e.
@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.
+is preferred instead of @qq{Time signature}. Only use capital
+letters for musical terms which demand them, e.g.
+@qq{D.S. al Fine}.
-For scheme functions, only include the final part, i.e.,
+@item
+For scheme function index entries, only include the final part, i.e.
@example
@@funindex modern-voice-cautionary
@end example
@item
-Preferred terms:
+Use American spelling. LilyPond's internal property
+names use this convention.
+
+@item
+Here is a list of preferred terms to be used:
@itemize
+@item
+@emph{Simultaneous} NOT concurrent.
@item
-In general, use the American spellings. The internal lilypond
-property names use this spelling.
+@emph{Measure}: the unit of music.
@item
-List of specific terms:
+@emph{Bar line}: the symbol delimiting a measure NOT barline.
-@example
-canceled
-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
+@item
+@emph{Note head} NOT notehead.
+
+@item
+@emph{Chord construct} NOT just chord (when referring to < ... >)
+
+@item
+@emph{Staff} NOT stave.
+
+@item
+@emph{Staves} NOT Staffs:
+Phrases such as
+@q{multiple @@internalsref@{Staff@}s}
+should be rephrased to
+@q{multiple @@internalsref@{Staff@} contexts}.
@end itemize
+
@end itemize
@item
move LSR-worthy material into LSR. Add the snippet, delete the
-material from the .itely file, and add a @@lilypondfile command.
+material from the @file{.itely} file, and add a @@lilypondfile command.
@item
check the examples and descriptions. Do they still work?
In general, any \set or \override commands should go in the
@qq{select snippets} section, which means that they should go in
-LSR and not the .itely file. For some cases, the command
+LSR and not the @file{.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.
@node Scripts to ease doc work
@section Scripts to ease doc work
-@subheading Stripping whitespace
+@subheading Building only one section of the documentation
-@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
+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.
+
+You can build a section of the documentation with:
@example
-scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
+scripts/auxiliar/doc-section.sh MANUAL SECTION
@end example
+@noindent
+where @code{SECTION} is the name of the file containing the section
+to be built, and @code{MANUAL} is 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:
-@subheading Sectioning commands
+@example
+scripts/auxiliar/doc-section.sh notation pitches
+@end example
-@warning{These commands add whitespace.}
+You can then see the generated document for the section at
-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
+tempdocs/pitches/out/pitches.html
+@end example
+
+According to
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1236,Lilypond issue 1236},
+the location of the lilypond git tree is taken from @code{$LILYPOND_GIT}
+if specified, otherwise it is auto-detected.
+
+It is assumed that compilation takes place in the @file{build/}
+subdirectory, but this can be overridden by setting the environment
+variable @code{LILYPOND_BUILD_DIR}.
+
+Similarly, output defaults to @file{build/tempdocs/} but this can be
+overridden by setting the environment variable
+@code{LILYPOND_TEMPDOCS}.
+
+This script will not work for building sections of the
+Contributors' guide. For building sections of the Contributors'
+Guide, use:
@example
-#!/bin/sh
-emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
+scripts/auxiliar/cg-section.sh SECTION
@end example
@noindent
-(save the above as something like @command{texinfo-menus.sh}, make
-it executable, then run @command{texinfo-menus.sh foo.itely})
+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
+@code{cg-section.sh} uses the same environment variables and
+corresponding default values as @code{doc-section.sh}.
-@subheading Updating doc with @command{convert-ly}
+@subheading Stripping whitespace and generating menus
-cd into @file{Documentation/} and run
+@warning{This script assumes that the file conforms to our doc
+policy; a few files still need work in this regard.}
+
+To automatically regenerate @code{@@menu} portions and strip
+whitespace, use:
@example
-find . -name '*.itely' | xargs convert-ly -e
+scripts/auxiliar/node-menuify.py @var{FILENAME}
@end example
-@noindent
-This also updates translated documentation.
+@subheading Stripping whitespace only
+
+@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 Updating doc with @command{convert-ly}
+
+Don't. This should be done by programmers when they add new
+features. If you notice that it hasn't been done, complain to
+@code{lilypond-devel}.
@node 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
+requires modifying files in @file{scm/*.scm}. Texinfo is allowed
in these docstrings.
Most documentation writers never touch these, though. If you want
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 experimented translators,
+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
@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
+@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.
@node Getting started with documentation translation
@subsection Getting started with documentation translation
-First, get the sources of branch @code{lilypond/translation} from the
+First, get the sources of branch @code{translation} from the
Git repository, see @ref{Starting with Git}.
@menu
where @var{MY-LANGUAGE} is the ISO 639 language code.
Finally, add a language definition for your language in
-@file{python/@/langdefs@/.py}.
+@file{python/langdefs.py}.
@node Documentation translation details
@@@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
+contains @code{@@untranslated}. That is, you should end up
for each untranslated node with something like
@example
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
+menus. This process should be made easier in the future, when the helper
script @command{texi-langutils.py} and the makefile target are updated.
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
+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{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}.
+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{Documentation/@/snippets/@/@var{filename}@/.ly},
+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{Documentation/@/@var{MY-LANGUAGE}/@/texidocs/@/@var{filename}@/.texidoc}.
+@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}
+@file{Documentation/@var{MY-LANGUAGE}/texidocs/@/@var{filename}.texidoc}
may contain
@example
"
@end example
-@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}.
-
@code{@@example} blocks need not be verbatim copies, e.g. variable
names, file names and comments should be translated.
@seeCommittishesUpdate
Global state of the translation is recorded in
-@file{Documentation/@/translations@/.itexi}, 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.
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/@/foo/@/every@/.itely}} with music snippets from
-@file{@var{foo/@/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/}):
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.
+Most of the changes in the LSR snippets included in the documentation concern
+the syntax, not the description inside @code{texidoc=""}. This implies that
+quite often you will have to update only the committish of the matching
+.texidoc file. This can be a tedious work if there are many snippets to be
+marked as up do date. You can use the following command to update the
+committishes at once:
+
+@example
+cd Documentation/LANG/texidocs
+sed -i -r 's/[0-9a-z]@{40@}/NEW-COMMITTISH/' *.texidoc
+@end example
@seealso
@ref{LSR work}.
@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,
+do it and delete the macro definition from @file{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
+@file{macros.itexi} until the documentation translation has been updated and
no longer uses this macro.
@item Update @file{*.tely} files completely with
@item Update sections finished in the English documentation; check
sections status at
+@smallexample
@uref{http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination}.
+@end smallexample
@item Update documentation PO. It is recommended not to update
strings which come from documentation that is currently deeply revised
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
+@item Translation work is made on
+@code{translation} branch. This branch is merged on
+@code{staging} once a week, approximately. Then,
+@code{master} branch is merged on
+@code{translation}, where the check-translation script (see
+@ref{Check state of translation}) shows changes in English docs which
+should be translated, and the cycle starts again.
+
+@item Translations may be pushed directly to
+@code{staging} only if they do not break compilation of LilyPond and
+its documentation. Those changes could be pushed to
+@code{translation} too, or alternatively translators could wait until
+they come from
+@code{master} the next time it is merged on
+@code{translation}. Similarly, changes matching
@code{stable/X.Y} are preferably made on
-@code{lilypond/X.Ytranslation}.
+@code{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 successfully.
+@item @code{translation} Git branch may be merged into
+@code{staging} branch only if LilyPond (@command{make all}) and
+documentation (@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 successful (in order to ease documentation compilation by
-translators), or when significant changes had been made in
-documentation in English in master branch.
+@item @command{make} and @command{make doc} are usually successful in
+@code{master} Git branch because those tests should have already
+succeeded in
+@code{staging} branch before merging.
+@code{master} branch may be merged into
+@code{translation} when significant changes had been made in
+documentation in English in
+@code{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}.
+cross-references, and operations described in
+@ref{Maintaining without updating translations}.
@end itemize
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{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
projects / lilypond.git / blobdiff