From a6d4d2492e33a175274278fcf74ed3270d028f5e Mon Sep 17 00:00:00 2001 From: John Mandereau Date: Fri, 24 Apr 2009 11:25:51 +0200 Subject: [PATCH] Update instructions for handling doc snippets - take text written by Carl in http://lists.gnu.org/archive/html/lilypond-devel/2009-04/msg00235.html as a starting point; - update instructions according to recent changes in makelsr.py; - (re)move duplicate information in input/{new,lsr}/README. --- Documentation/devel/doc-work.itexi | 6 ++- Documentation/devel/lsr-work.itexi | 59 ++++++++++++++++++++++++++---- input/lsr/README | 21 ++--------- input/new/README | 15 +------- 4 files changed, 61 insertions(+), 40 deletions(-) diff --git a/Documentation/devel/doc-work.itexi b/Documentation/devel/doc-work.itexi index 931f5874f4..b6bbe63d3c 100644 --- a/Documentation/devel/doc-work.itexi +++ b/Documentation/devel/doc-work.itexi @@ -877,7 +877,7 @@ lilypond examples. Making easily-understandable examples is much harder than it looks. -@subsubheading TWEAKS +@subsubheading Tweaks In general, any \set or \override commands should go in the @qq{select snippets} section, which means that they should go in @@ -915,6 +915,10 @@ or upgrading tweaks is creating tweaks to deal with known issues. It would be ideal if every significant known issue had a workaround to avoid the difficulty. +@seealso + +@ref{Adding and editing snippets}. + @node Updating docs with convert-ly @section Updating doc with @command{convert-ly} diff --git a/Documentation/devel/lsr-work.itexi b/Documentation/devel/lsr-work.itexi index 2fcbb56515..8f38ec2899 100644 --- a/Documentation/devel/lsr-work.itexi +++ b/Documentation/devel/lsr-work.itexi @@ -18,25 +18,64 @@ The @uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)} is a collection of lilypond examples. A subset of these examples are automatically imported into the documentation, making it easy -for users to contribute to the docs without learning git and -texinfo. +for users to contribute to the docs without learning Git and +Texinfo. @node Adding and editing snippets @section Adding and editing snippets -When you create (or find!) a nice snippet, please add it to LSR. Go -to @uref{http://lsr.dsi.unimi.it/, LSR} and log in (if you haven't -already, create an account). Follow the instructions on the website. +@subheading General guidelines + +When you create (or find!) a nice snippet, if it supported by LilyPond +version running on LSR, please add it to LSR. Go to +@uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't +already, create an account. Follow the instructions on the website. These instructions also explain how to modify existing snippets. -If you think the snippet is particularly informative and you think -it should be included in the documentation, tag it with @qq{docs} -and one or more other categories. +If you think the snippet is particularly informative and you think it +should be included in the documentation, tag it with @qq{docs} and one +or more other categories, or ask somebody who has editing permissions to +do it on the development list. Please make sure that the lilypond code follows the guidelines in @ref{LilyPond formatting}. +If a new snippet created for documentation purposes compiles with +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 +current LSR version, the snippet should be added to @file{input/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 + +@example +scripts/auxiliar/makelsr.py +@end example + +Be sure that @command{make web} runs successfully before submitting a +patch, to prevent breaking compilation. + +@subheading Formatting snippets in @file{input/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. +@} +@end example + +and name the file @file{snippet-title.ly}. + @node Approving snippets @section Approving snippets @@ -106,6 +145,10 @@ Do a git add / commit / push. @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}. + @node Fixing snippets in LilyPond sources @section Fixing snippets in LilyPond sources diff --git a/input/lsr/README b/input/lsr/README index 8c8683f216..f3c1608129 100644 --- a/input/lsr/README +++ b/input/lsr/README @@ -1,20 +1,5 @@ -This directory contains examples generated automatically from LSR: +This directory contains examples generated automatically from LSR http://lsr.dsi.unimi.it/ -To update this directory, do at top of the source tree - -scripts/auxiliar/makelsr.py DIR - -where DIR is the directory unpacked from lsr-snippets-doc-DATE tarball -available on http://lsr.dsi.unimi.it/download. - -Snippets in input/new may "overwrite" snippets from LSR, e.g. for -snippets that convert-ly can't automatically convert to current ly -syntax; snippets may also be added to input/new to demonstrate new -features in development series. - -Any changes made to .ly files will be lost next time makelsr.py is -run. Please make updates to the LSR database or input/new directly. -You must be an editor to change "approved" snippets in LSR; otherwise -just copy the snippet you want to modify in a new snippet, and tag it -with the "correction-wanted" tag. +To update this directory and find addtional information, see +the Contributors' Guide, section "LSR to Git". diff --git a/input/new/README b/input/new/README index 058fd73515..1b226cf95e 100644 --- a/input/new/README +++ b/input/new/README @@ -2,16 +2,5 @@ This directory is for examples of new features in the current unstable development series. These snippets will be added to LSR when it supports a version of LilyPond that includes these features. -When adding a file to this directory, please start the file with - -\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. -} - - -and name the file snippet-title.ly. +See additional instructions in the Contributors' Guide, section +Adding and editing snippets. -- 2.39.2