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.
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
@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
-If a heading is desired without creating a node, please use
+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
@end example
@item
-Sectioning commands (@@node and @@section) must not appear
-inside an @@ignore. Separate those commands with a space, ie
-@@n@tie{}ode.
+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
@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
+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
+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.
+
+i.e. @qq{...setting the @code{transparent} property leaves the object where it
+is, but makes it invisible.}
@item
If possible, only write one bar per line.
@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
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: \chordmode @{c e g@}
+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@}
but instead: \chordmode @{ c e g @}
@end example
@item
-Use @{ @} marks for additional @code{\markup} format comands; ie
+Use @{ @} marks for additional @code{\markup} format commands; i.e.
@example
not: c^\markup \tiny\sharp
@end example
@item
-Remove any space around @code{<} @code{>} marks; ie
+Remove any space around @code{<} @code{>} marks; i.e.
@example
not: < c e g > 4
@unnumberedsubsubsec Cross references
Enter the exact @code{@@node} name of the target reference between
-the brackets (eg.@tie{}@w{@samp{@@ref@{Syntax survey@}}}).
+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{@@ruser@{@dots{}@}} --- link to Notation Reference.
@item
-@code{@@rweb@{@dots{}@}} --- link to General Informaion.
+@code{@@rweb@{@dots{}@}} --- link to General Information.
@end itemize
@item
@code{@@uref@{@var{URL}[, @var{link text}]@}} --- link to an
-external url.
+external url. Use within an @code{@@example ... @@end example}.
+
+@example
+@@example
+@@uref@{URL [, link text ]@}
+@@end example
+@end example
@end 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.
+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}
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@{\relative c''@}@}}}} will display
+@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@{\relative c''@}@}}} wrongly produces
-@q{@w{@code{\relative c@quoteright{}@quoteright{}}}} in PDF.
+@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).
+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@}}).
+@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
-extraneous indentation (ie. don't start every line with
+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:
@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
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
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 @qq{sentence runs directly into the example} method is not
@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 (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).
+
+@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
@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.
+
+The script is available as:
@example
-scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
+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}.
-@subheading Sectioning commands
+Assuming that no customization is required, you can setup the
+single section build with:
-@warning{These commands add whitespace.}
+@example
+mkdir $HOME/lilypond/tempdocs
+cp $HOME/lilypond/Documentation/out/version.itexi $HOME/lilypond/tempdocs
+@end example
-The emacs @code{M-x texinfo-all-menus-update} command will
-regenerate @@menu blocks. This can also be run with this
-command-line script:
+You can then build a section of the documentation with:
@example
-#!/bin/sh
-emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
+scripts/auxiliar/doc-section.sh MANUAL 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 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 and generating menus
+
+@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
+scripts/auxiliar/node-menuify.py @var{FILENAME}
+@end example
+
+
+@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}
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,
-and we regularly discuss translations issues common to all languagues.
+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
+@code{subscribe} and an empty message body. Unless mentioned explicitly,
or except if a translations coordinator contacts you privately, you
-should send questions, remarks, patches to this list
-@code{translations@@lilynet.net}; especially note that the traffic is so
-high on English-speaking list @code{lilypond-user@@gnu.org} that it may
-take months before your request or contribution is handled if you send a
-email to these lists.
+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::
least the documentation so that you can check the output yourself and
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}.
+
@node Which documentation can be translated
@unnumberedsubsubsec Which documentation can be translated
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
original text; for instance, in the translation of the web site section
Community, you may take this into account depending on what you know the
community in your language is willing to support, which is possible only
-if you personnally assume this support, or there exists a public forum
+if you personally assume this support, or there exists a public forum
or mailing list listed in Community for LilyPond in your language:
@itemize
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}.
-Additionnally, you may translate the snippet's title in @code{doctitle}
+@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
@noindent
Then, you should get these translated strings into compiled snippets in
-@file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
+@file{Documentation/@/snippets}, see @q{General guidelines} in @ref{Adding
and editing snippets}.
@code{@@example} blocks need not be verbatim copies, e.g. variable
@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 CHECKED_FILES=@var{MY_LANGUAGE/@var{manual}/foo.itely} update-translation
@end example
-For each file to be udpated, @code{update-translation} will open your
+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.
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
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
+@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
@end example
A special case is updating Snippet documentation strings in
-@file{Documentation/@var{MY-LANGUAGE}/texidocs}. For these to be
+@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/}.
+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}
+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
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}.
@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{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