Doc-fr: update texidoc markers

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

diff --git a/Documentation/contributor/lsr-work.itexi b/Documentation/contributor/lsr-work.itexi
index b3d49963440ce6b312376f31c78c2204d7cc0429..1a64a55c8fbcb2d9c77d4cf2445069331abe6e12 100644 (file)
--- a/Documentation/contributor/lsr-work.itexi
+++ b/Documentation/contributor/lsr-work.itexi
@@ -1,4 +1,4 @@
-@c -*- coding: us-ascii; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-

 @node LSR work
 @chapter LSR work
 
 @node LSR work
 @chapter LSR work
 


@@ -8,6 +8,7 @@
 * Approving snippets::
 * LSR to Git::
 * Fixing snippets in LilyPond sources::
 * Approving snippets::
 * LSR to Git::
 * Fixing snippets in LilyPond sources::

+* Renaming a snippet::

 * Updating LSR to a new version::
 @end menu
 
 * Updating LSR to a new version::
 @end menu
 


@@ -47,34 +48,53 @@ LilyPond version currently on LSR, it should be added to LSR, and a
 reference to the snippet should be added to the documentation.
 
 If the new snippet uses new features that are not available in the
 reference to the snippet should be added to the documentation.
 
 If the new snippet uses new features that are not available in the

-current LSR version, the snippet should be added to @file{input/new} and
-a reference should be added to the manual.
+current LSR version, the snippet should be added to
+@file{Documentation/snippets/new} and a reference should be added to the
+manual.

 
 

-Snippets created or updated in @file{input/new} should be copied to
-@file{input/lsr} by invoking at top of the source tree
+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
 scripts/auxiliar/makelsr.py
 @end example
 
 
 @example
 scripts/auxiliar/makelsr.py
 @end example
 

+@noindent
+This also copies translated texidoc fields and snippet titles into
+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;
+see @ref{Documentation translation maintenance} for details about
+updating the docs; in particular, see @ref{Updating translation
+committishes} to learn how to mark these translated fields as fully
+updated.
+

 Be sure that @command{make doc} runs successfully before submitting a
 patch, to prevent breaking compilation.
 
 Be sure that @command{make doc} runs successfully before submitting a
 patch, to prevent breaking compilation.
 

-@subheading Formatting snippets in @file{input/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 @{
 
 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
 
 @}
 @end example
 

+@noindent

 and name the file @file{snippet-title.ly}.
 
 
 and name the file @file{snippet-title.ly}.
 
 


@@ -100,6 +120,10 @@ the @qq{docs} tag and at least one other tag.
 If the snippet is tagged with @qq{docs}, check to see if it
 matches our guidelines for @ref{LilyPond formatting}.
 
 If the snippet is tagged with @qq{docs}, check to see if it
 matches our guidelines for @ref{LilyPond formatting}.
 

+Also, snippets tagged with @qq{docs} should not be explaining
+(replicating) existing material in the docs.  They should not
+refer to the docs; the docs should refer to them.
+

 @item
 If the snippet uses scheme, check that everything looks good and
 there are no security risks.
 @item
 If the snippet uses scheme, check that everything looks good and
 there are no security risks.


@@ -117,79 +141,117 @@ step @strong{VERY SERIOUSLY}.}
 @enumerate
 
 @item
 @enumerate
 
 @item

-Make sure that @command{convert-ly} and @command{lilypond} commands in
-current PATH are in a bleeding edge version -- latest release from
-master branch, or even better a fresh snapshot from Git master branch.
+Make sure that @command{convert-ly} and @command{lilypond} are a
+bleeding edge version -- the latest release or even better a fresh
+snapshot from Git master.

 
 @item
 
 @item

-From the top source directory, run:
+Start by creating a list of updated snippets from your local
+repository.  From the top source directory, run:

 
 @example
 
 @example

+scripts/auxiliar/makelsr.py
+@end example
+
+Commit the changes and make a patch.  Check the patch has nothing
+other than minor changes - in particular changes to the commitish
+for translations.  If all is good and you're confident in what
+you've done, this can be pushed directly to staging.
+
+@item
+Next, download the updated snippets and run makelsr against them.
+From the top source directory, run:
+
+@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}
 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
 
 @noindent

-where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
+where @var{YYYY-MM-DD} is the current date, e.g. 2011-12-25.

 
 @item
 Follow the instructions printed on the console to manually check for
 
 @item
 Follow the instructions printed on the console to manually check for

-unsafe files.
+unsafe files.  These are:
+
+@example
+Unsafe files printed in lsr-unsafe.txt: CHECK MANUALLY!
+  git add Documentation/snippets/*.ly
+  xargs git diff HEAD < lsr-unsafe.txt
+@end example
+
+First, it's important to check for any added files and add them to
+the files git is tracking.  Run @code{git status} and look
+carefully to see if files have been added.  If so, add them with
+@code{git add}.
+
+As the console says, makelsr creates a list of possibly unsafe
+files in @file{lsr-unsafe.txt} by running @code{lilypond} against each
+snippet using the @code{-dsafe} switch.  This list can be quite
+long.  However, by using the command @code{xargs git diff HEAD < lsr-unsafe.txt}
+git will take that list and check whether any of the snippets are
+different from the snippet already in master.  If any is different
+it must be checked manually VERY CAREFULLY.

 
 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 command into our source tree if you do not do this!  Take this
 step @strong{VERY SERIOUSLY}.}
 
 
 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
 command into our source tree if you do not do this!  Take this
 step @strong{VERY SERIOUSLY}.}
 

+If there is any doubt about any of the files, you are strongly
+advised to run a review on Rietveld.
+

 @item
 @item

-Do a git add / commit / push.
+If a Review is not needed, commit the changes and push to staging.

 
 @end enumerate
 
 
 @end enumerate
 

-Note that whenever there is one snippet from @file{input/new} and the
-other from LSR with the same file name, the one from @file{input/new}
-will be copied by @command{makelsr.py}.
+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
+by @command{makelsr.py}.

 
 
 @node Fixing snippets in LilyPond sources
 @section Fixing snippets in LilyPond sources
 
 
 
 @node Fixing snippets in LilyPond sources
 @section Fixing snippets in LilyPond sources
 

-In case some snippet from @file{input/lsr} cause the documentation
-compilation to fail, the following steps should be followed to fix it
-reliably.
+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
 
 @enumerate
 
 @item
 Look up the snippet filename @file{@var{foo}.ly} in the error output

-or log, then fix the file @file{input/lsr/@var{foo}.ly} to make the
-documentation build succesfully.
+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
 
 @example
 
 @item
 Determine where it comes from by looking at its first line, e.g. run
 
 @example

-head -1 input/lsr/@var{foo}.ly
+head -1 Documentation/snippets/@var{foo}.ly

 @end example
 
 @item
 @strong{In case the snippet comes from LSR}, apply the fix to the
 @end example
 
 @item
 @strong{In case the snippet comes from LSR}, apply the fix to the

-snippet in LSR and send a notification email to a LSR editor with CC
-to the development list -- see @ref{Adding and editing snippets}.  The
+snippet in LSR and send a notification email to a LSR editor with CC to
+the development list -- see @ref{Adding and editing snippets}.  The

 failure may sometimes not be caused by the snippet in LSR but by the
 failure may sometimes not be caused by the snippet in LSR but by the

-syntax conversion made by @command{convert-ly}; in this case, try to
-fix @command{convert-ly} or report the problem on the development
-list, then run @command{makelsr.py} again, see @ref{LSR to Git}.  In
-some cases, 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{input/new}, then run @command{makelsr.py}.
+syntax conversion made by @command{convert-ly}; in this case, try to fix
+@command{convert-ly} or report the problem on the development list, then
+run @command{makelsr.py} again, see @ref{LSR to Git}.  In some cases,
+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}.

 
 @item
 
 @item

-@strong{In case the snippet comes from} @file{input/new}, apply in
-@file{input/new/@var{foo}.ly} the same fix you did in
-@file{input/lsr/@var{foo}.ly}.  In case the build failure was caused
-by a translation string, you may have to fix
+@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
+was caused by a translation string, you may have to fix

 @file{input/texidocs/@var{foo}.texidoc} instead.
 
 @item
 @file{input/texidocs/@var{foo}.texidoc} instead.
 
 @item


@@ -198,6 +260,31 @@ In any case, commit all changes to Git.
 @end enumerate
 
 
 @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
 
 @node Updating LSR to a new version
 @section Updating LSR to a new version


@@ -209,13 +296,13 @@ 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
 @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
 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{input/new/} into
-the tarball.
+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.

 
 You must not rename any files during this, or the next, stage.
 
 
 You must not rename any files during this, or the next, stage.
 


@@ -235,18 +322,19 @@ web-2.0 volunteers will fix it.  It's not our problem.
 Create a tarball and send it back to Sebastiano.
 
 @item
 Create a tarball and send it back to Sebastiano.
 
 @item

-When LSR has been updated, download another snippet tarball,
-verify that the relevant snippets from @file{input/new/} were
-included, then delete those snippets from @file{input/new/}.
+When LSR has been updated, download another snippet tarball, verify that
+the relevant snippets from @file{Documentation/snippets/new/} were
+included, then delete those snippets from
+@file{Documentation/snippets/new/}.

 
 @end enumerate
 
 
 
 @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.
 
 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
 #!/bin/bash
 
 for LILYFILE in *.ly


@@ -257,4 +345,4 @@ do
 done
 
 grep failed *.txt
 done
 
 grep failed *.txt

-@end example
+@end smallexample