* Approving snippets::
* LSR to Git::
* Fixing snippets in LilyPond sources::
+* Renaming a snippet::
* Updating LSR to a new version::
@end menu
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
@example
\version "2.x.y"
\header @{
- lsrtags = "rhythms,expressive-marks" % use existing LSR tags other than
-% 'docs'; see makelsr.py for the list of tags used to sort snippets.
- texidoc = "This code demonstrates ..." % this will be formated by Texinfo
- doctitle = "Snippet title" % please put this at the end so that
- the '% begin verbatim' mark is added correctly by makelsr.py.
+% Use existing LSR tags other than 'docs'; see makelsr.py for
+% the list of tags used to sort snippets. E.g.:
+ lsrtags = "rhythms,expressive-marks"
+% This texidoc string will be formatted by Texinfo
+ texidoc = "
+This code demonstrates ...
+"
+% Please put doctitle last so that the '% begin verbatim'
+% mark will be added correctly by makelsr.py.
+ doctitle = "Snippet title"
@}
@end example
-\noindent
-and name the file @file{snippet@/-title@/.ly}.
+@noindent
+and name the file @file{snippet-title.ly}.
@node Approving snippets
@item
From the top source directory, run:
-@example
+@smallexample
wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
-@end example
+@end smallexample
@noindent
where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
@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
-documentation build succesfully.
+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 successfully.
@item
Determine where it comes from by looking at its first line, e.g. run
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.
@end enumerate
+@node Renaming a snippet
+@section Renaming a snippet
+
+Due to the potential duality of snippets (i.e. they may exist both
+in the LSR database, and in @code{Documentation/snippets/new/}),
+this process is a bit more involved than we might like.
+
+@enumerate
+@item
+Send an email LSR editor, requesting the renaming.
+
+@item
+The LSR editor does the renaming (or debates the topic with you),
+then warns the LSR-to-git person (wanted: better title) about the
+renaming.
+
+@item
+LSR-to-git person does his normal job, but then also renames any
+copies of the snippets in @code{Documentation/snippets/new/}, and
+any instances of the snippet name in the documentation.
+
+@code{git grep} is highly recommended for this task.
+
+@end enumerate
+
@node Updating LSR to a new version
@section Updating LSR to a new version
@item
Download the latest snippet tarball, extract it, and run
@code{convert-ly} on all files using the command-line option
-@code{--to=VERSION} to ensure snippets are updated to the
+@option{--to=@var{version}} to ensure snippets are updated to the
correct stable version.
@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
-Here is a shell script to run all @code{.ly} files in a directory
+Here is a shell script to run all @file{.ly} files in a directory
and redirect terminal output to text files, which are then
searched for the word "failed" to see which snippets do not compile.
-@example
+@smallexample
#!/bin/bash
for LILYFILE in *.ly
done
grep failed *.txt
-@end example
+@end smallexample
projects / lilypond.git / blobdiff