[doc] Handle leading dash in @code.

[lilypond.git] / Documentation / contributor / lsr-work.itexi

diff --git a/Documentation/contributor/lsr-work.itexi b/Documentation/contributor/lsr-work.itexi
index 94cf04ec1d5aa318a8591aa74383c52fcd3d02ba..1ba87306404609fcaec18eddf593403bda913a99 100644 (file)
--- a/Documentation/contributor/lsr-work.itexi
+++ b/Documentation/contributor/lsr-work.itexi
@@ -8,6 +8,7 @@
 * Approving snippets::
 * LSR to Git::
 * Fixing snippets in LilyPond sources::
+* Renaming a snippet::
 * Updating LSR to a new version::
 @end menu
 
@@ -80,14 +81,20 @@ 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}.
 
 
@@ -141,11 +148,11 @@ master branch, or even better a fresh snapshot from Git master branch.
 @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.
@@ -181,7 +188,7 @@ followed to fix it reliably.
 @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.
+documentation build successfully.
 
 @item
 Determine where it comes from by looking at its first line, e.g. run
@@ -217,6 +224,31 @@ 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
@@ -228,7 +260,7 @@ To update LSR, perform the following steps:
 @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
@@ -262,11 +294,11 @@ included, then delete those snippets from
 @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
@@ -277,4 +309,4 @@ do
 done
 
 grep failed *.txt
-@end example
+@end smallexample