make grand-replace
@end example
-Internally, this invokes the script @file{scripts/build/grand-replace.py},
+Internally, this invokes the script @file{scripts/@/build/@/grand@/-replace@/.py},
which performs a regular expression substitution for old-year -> new-year
wherever it finds a valid copyright notice.
-Note that snapshots of third party files such as @file{texinfo.tex} should
-not be included in the automatic update; @file{grand-replace.py} ignores these
+Note that snapshots of third party files such as @file{texinfo@/.tex} should
+not be included in the automatic update; @file{grand@/-replace@/.py} ignores these
files if they are listed in the variable @code{copied_files}.
@c Word counts are updated automatically by translations-status.py
-Translation of @file{Documentation/foo/bar} should be
-@file{Documentation/@var{LANG}/foo/bar}. Unmentioned files should not
+Translation of @file{Documentation/@/foo/@/bar} should be
+@file{Documentation/@/@var{LANG}/@/foo/@/bar}. Unmentioned files should not
be translated.
Priorities:
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
@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
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
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
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 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
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
@item
If the issue has a notation example which fits in one system,
-generate a small @file{bug.preview.png} file with:
+generate a small @file{bug@/.preview@/.png} file with:
@example
lilypond -dpreview bug.ly
@item
If the issue has an example which requires more than one system
-(i.e. a spacing bug), generate a @file{bug.png} file with:
+(i.e. a spacing bug), generate a @file{bug@/.png} file with:
@example
lilypond --png bug.ly
@item
If the issue requires multi-page output, then generate a
-@file{bug.pdf} file with the normal:
+@file{bug@/.pdf} file with the normal:
@example
lilypond --png bug.ly
If the new snippet uses new features that are not available in the
current LSR version, the snippet should be added to
-@file{Documentation/snippets/new} and a reference should be added to the
+@file{Documentation/@/snippets/@/new} and a reference should be added to the
manual.
-Snippets created or updated in @file{Documentation/snippets/new} should
-be copied to @file{Documentation/snippets} by invoking at top of the
+Snippets created or updated in @file{Documentation/@/snippets/@/new} should
+be copied to @file{Documentation/@/snippets} by invoking at top of the
source tree
@example
@noindent
This also copies translated texidoc fields and snippet titles into
-snippets in @file{Documentation/snippets}. Note: this, in turn, could
+snippets in @file{Documentation/@/snippets}. Note: this, in turn, could
make the translated texidoc fields to appear as out of sync when you
run @code{make check-translation}, if the originals changed from the
last translation update, even if the translations are also updated;
Be sure that @command{make doc} runs successfully before submitting a
patch, to prevent breaking compilation.
-@subheading Formatting snippets in @file{Documentation/snippets/new}
+@subheading Formatting snippets in @file{Documentation/@/snippets/@/new}
When adding a file to this directory, please start the file with
@}
@end example
-and name the file @file{snippet-title.ly}.
+\noindent
+and name the file @file{snippet@/-title@/.ly}.
@node Approving snippets
@end enumerate
Note that whenever there is one snippet from
-@file{Documentation/snippets/new} and the other from LSR with the same
-file name, the one from @file{Documentation/snippets/new} will be copied
+@file{Documentation/@/snippets/@/new} and the other from LSR with the same
+file name, the one from @file{Documentation/@/snippets/@/new} will be copied
by @command{makelsr.py}.
@node Fixing snippets in LilyPond sources
@section Fixing snippets in LilyPond sources
-In case some snippet from @file{Documentation/snippets} causes the
+In case some snippet from @file{Documentation/@/snippets} causes the
documentation compilation to fail, the following steps should be
followed to fix it reliably.
@enumerate
@item
-Look up the snippet filename @file{@var{foo}.ly} in the error output
-or log, then fix the file @file{Documentation/snippets/@var{foo}.ly} to make the
+Look up the snippet filename @file{@var{foo}@/.ly} in the error output
+or log, then fix the file @file{Documentation/@/snippets/@/@var{foo}@/.ly} to make the
documentation build succesfully.
@item
when some features has been introduced or vastly changed so it requires
(or takes significant advantage of) important changes in the snippet, it
is simpler and recommended to write a new version of the snippet in
-@file{Documentation/snippets/new}, then run @command{makelsr.py}.
+@file{Documentation/@/snippets/@/new}, then run @command{makelsr.py}.
@item
@strong{In case the snippet comes from}
-@file{Documentation/snippets/new}, apply in
-@file{Documentation/snippets/new/@var{foo}.ly} the same fix you did in
-@file{Documentation/snippets/@var{foo}.ly}. In case the build failure
+@file{Documentation/@/snippets/@/new}, apply in
+@file{Documentation/@/snippets/@/new/@/@var{foo}@/.ly} the same fix you did in
+@file{Documentation/@/snippets/@/@var{foo}@/.ly}. In case the build failure
was caused by a translation string, you may have to fix
-@file{input/texidocs/@var{foo}.texidoc} instead.
+@file{input/@/texidocs/@/@var{foo}@/.texidoc} instead.
@item
In any case, commit all changes to Git.
@item
Copy relevant snippets (i.e., snippets whose version is equal to or less
than the new version of LilyPond) from
-@file{Documentation/snippets/new/} into the tarball.
+@file{Documentation/@/snippets/@/new/} into the tarball.
You must not rename any files during this, or the next, stage.
@item
When LSR has been updated, download another snippet tarball, verify that
-the relevant snippets from @file{Documentation/snippets/new/} were
+the relevant snippets from @file{Documentation/@/snippets/@/new/} were
included, then delete those snippets from
-@file{Documentation/snippets/new/}.
+@file{Documentation/@/snippets/@/new/}.
@end enumerate
make -C lily clean && make -C lily
@end example
-@item Create a graphviz-compatible .ly file
+@item Create a graphviz-compatible @file{.ly} file
-In order to use the graphviz utility, the .ly file must include
-@file{ly/graphviz-init.ly}, and should then specify the
+In order to use the graphviz utility, the @file{.ly} file must include
+@file{ly/@/graphviz@/-init@/.ly}, and should then specify the
grobs and symbols that should be tracked. An example of this
is found in @file{input/regression/graphviz.ly}.
longer.
Running @command{make@tie{}check} will leave an HTML page
-@file{out/test-results/index.html}. This page shows all the
+@file{out/@/test@/-results/@/index@/.html}. This page shows all the
important differences that your change introduced, whether in the
layout, MIDI, performance or error reporting.
@end example
The regtest output will then be available in
-@file{input/regression/out-test}.
-@file{input/regression/out-test/collated-examples.html}
+@file{input/@/regression/@/out@/-test}.
+@file{input/@/regression/@/out@/-test/@/collated@/-examples@/.html}
contains a listing of all the regression tests that were run,
but none of the images are included. Individual images are
also available in this directory.
@end example
After @samp{make@tie{}check} is complete, a regression test comparison
-will be available at @file{out/test-results/index.html}.
+will be available at @file{out/@/test@/-results/@/index@/.html}.
For each regression test that differs between the baseline and the
changed code, a regression test entry will displayed. Ideally, the
only changes would be the changes that you were working on. If
code.
@warning{
-The special regression test @file{test-output-distance.ly} will always
+The special regression test @file{test@/-output@/-distance@/.ly} will always
show up as a regression. This test changes each time it is run, and
serves to verify that the regression tests have, in fact, run.}
make test-redo
@end example
-This updates the regression list at @file{out/test-results/index.html}.
-It does @emph{not} redo @file{test-output-distance.ly}.
+This updates the regression list at @file{out/@/test@/-results/@/index@/.html}.
+It does @emph{not} redo @file{test@/-output@/-distance@/.ly}.
When all regressions have been resolved, the output list will be empty.
can be used to test any MusicXML implementation.
The MusicXML regression tests are found at
-@file{input/regression/musicxml/}.
+@file{input/@/regression/@/musicxml/}.
The output resulting from running these tests
through @samp{muscxml2ly} followed by @samp{lilypond} is
make LILYPOND_BRANCH=stable/2.12 lilypond
@end example
-@item Check the regtest comparison in @file{uploads/webtest/} for
+@item Check the regtest comparison in @file{uploads/@/webtest/} for
any unintentional breakage. More info in
@ref{Precompiled regression tests}
@enumerate
@item If you're not right user on the webserver, remove the "t"
-from the rsync command in @file{test-lily/rsync-lily-doc.py} and
-@file{test-lily/rsync-test.py}
+from the rsync command in @file{test@/-lily/@/rsync@/-lily@/-doc@/.py} and
+@file{test@/-lily/@/rsync@/-test@/.py}
@code{graham} owns v2.13; @code{han-wen} owns v2.12.
@item
To run the program from the command line, navigate to the
-directory containing @file{lily-git.tcl} and enter:
+directory containing @file{lily@/-git@/.tcl} and enter:
@example
wish lily-git.tcl
@subsubheading 1. Get source / Update source
When you click the @qq{Get source} button, @command{lily-git} will
-create a directory called @file{lilypond-git/} within your home
+create a directory called @file{lilypond@/-git/} within your home
directory, and will download the source code into that
directory (around 55Mb). When the process is finished, the
@qq{Command output} window will display @qq{Done}, and the button
label will change to say @qq{Update source}.
-Navigate to the @file{lilypond-git/} directory to view the source
+Navigate to the @file{lilypond@/-git/} directory to view the source
files. You should now be able to modify the source files using
your normal text editor.
hopelessly confused!}
The button labeled @qq{Abort changes -- Reset to origin} will copy
-all changed files to a subdirectory of @file{lilypond-git/} named
-@file{aborted_edits/}, and will reset the repository to the
+all changed files to a subdirectory of @file{lilypond@/-git/} named
+@file{aborted@/_edits/}, and will reset the repository to the
current state of the remote repository (at @code{git.sv.gnu.org}).
Once Git is installed, you'll need to create a new directory where
your initial repository will be stored (the example below uses
-@file{~/lilypond-git/}, where @code{~} represents your home
+@file{~/lilypond@/-git/}, where @code{~} represents your home
directory). Run @command{git@tie{}init} from within the new
directory to initialize an empty repository:
@subsubheading Technical details
-This creates (within the @file{~/lilypond-git/} directory) a
+This creates (within the @file{~/lilypond@/-git/} directory) a
subdirectory called @file{.git/}, which Git uses to keep track of
changes to the repository, among other things. Normally you don't
need to access it, but it's good to know it's there.
@warning{Throughout the rest of this manual, all command-line
input should be entered from the top directory of the Git
-repository being discussed (eg. @file{~/lilypond-git/}). This is
+repository being discussed (eg. @file{~/lilypond@/-git/}). This is
referred to as a @emph{top source directory}.}
Before downloading a copy of the main LilyPond repository, you
Using the @command{git@tie{}config} command @emph{without} the
@command{--global} option configures repository-specific settings,
-which are stored in the file @file{.git/config}. This file is
+which are stored in the file @file{.git/@/config}. This file is
created when a repository is initialized (using
@command{git@tie{}init}), and by default contains these lines:
@end example
By now the source files should be accessible---you should be able
-to edit any files in the @file{lilypond-git/} directory using a
+to edit any files in the @file{lilypond@/-git/} directory using a
text editor of your choice. But don't start just yet! Before
editing any source files, learn how to keep your changes organized
and prevent problems later---read @ref{Basic Git procedures}.
@subsubheading Technical Details
The @command{git@tie{}remote@tie{}add} command should add some
-lines to your local repository's @file{.git/config} file:
+lines to your local repository's @file{.git/@/config} file:
@example
[remote "origin"]
The @command{git@tie{}config} command mentioned above adds the
line @code{rebase = true} to the master branch in your local
-repository's @file{.git/config} file:
+repository's @file{.git/@/config} file:
@example
[branch "master"]
@end example
When prompted for a location to save the key, press <ENTER> to
-accept the default location (@file{~/.ssh/id_dsa}).
+accept the default location (@file{~/.ssh/@/id_dsa}).
Next you are asked to enter an optional passphrase. On most
systems, if you use a passphrase, you will likely be prompted for
@end example
After setting up your passphrase, your private key is saved as
-@file{~/.ssh/id_dsa} and your public key is saved as
-@file{~/.ssh/id_dsa.pub}.
+@file{~/.ssh/@/id_dsa} and your public key is saved as
+@file{~/.ssh/@/id_dsa@/.pub}.
@item
Register your public SSH @q{dsa} key with Savannah. From the
@qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
-then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
+then paste the contents of your @file{~/.ssh/@/id_dsa@/.pub} file into
one of the @qq{Authorized keys} text fields, and click
@qq{Update}.
@end example
The list of known hosts is stored in the file
-@file{~/.ssh/known_hosts}.
+@file{~/.ssh/@/known@/_hosts}.
At this point, you are prompted for your passphrase if you have
one, then Git will attempt a pull.
@item
The @command{git@tie{}config} commands above should modify your
-local repository's @file{.git/config} file. These lines:
+local repository's @file{.git/@/config} file. These lines:
@example
[remote "origin"]
@item
Similarly, the
@command{git@tie{}config@tie{}push.default@tie{}matching} command
-should add these lines to @file{.git/config}:
+should add these lines to @file{.git/@/config}:
@example
[push]
@subheading Initial setup
You should symlink your own @file{~/lilypond/} to
-@file{~graham/lilypond/}
+@file{~graham/@/lilypond/}
If this directory does not exist, make it. Git master should go
-in @file{~/lilypond/lilypond-git/} but make sure you enable:
+in @file{~/lilypond/@/lilypond@/-git/} but make sure you enable:
@example
git config core.filemode false
@end example
-If you have created any files in @file{~graham/lilypond/} then
+If you have created any files in @file{~graham/@/lilypond/} then
please run:
@example
To reduce the CPU burden on the shared host (as well as some
-security concerns), the @file{Documentation/pictures/} and
-@file{Documentation/web/ly-examples/} directories are @strong{not}
+security concerns), the @file{Documentation/@/pictures/} and
+@file{Documentation/@/web/@/ly-examples/} directories are @strong{not}
compiled. If you modify any files in those directories, a user in
-the @code{lilypond} group must upload them to @file{~graham/media}
+the @code{lilypond} group must upload them to @file{~graham/@/media}
on the host.
Upload latest pictures/ and ly-examples/ (local script):
@subsubheading Additional information
Some information about the website is stored in
-@file{~graham/lilypond/*.txt}; this information should not be
+@file{~graham/@/lilypond/@/*.txt}; this information should not be
shared with people without trusted access to the server.
however, please note that this command is not designed for being
run multiple times. If you see unexpected output (mainly the page
footers getting all messed up), then delete your
-@file{out-website} directory and run @code{make website} again.
+@file{out@/-website} directory and run @code{make website} again.
@item
Some of the translation infrastructure is defined in python files;
@item
Translations are not included by default in @code{make website}.
To test your translation, edit the @code{WEB_LANGS} line in
-@file{make/website.make}. Do not submit a patch to add your language
+@file{make/@/website@/.make}. Do not submit a patch to add your language
to this file unless @code{make website} completes with less than 5
warnings.
projects / lilypond.git / commitdiff