X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fprogramming-work.itexi;h=819534b4ad0b23127f1ff304da1e4a56473fa558;hb=4e7839892d676e4863e07e11ea4968cffe34f97f;hp=0897ca125211074cb7d986a1a457cc826520898f;hpb=75195f1420ec4730bf220364116394104b711b0a;p=lilypond.git diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi index 0897ca1252..819534b4ad 100644 --- a/Documentation/contributor/programming-work.itexi +++ b/Documentation/contributor/programming-work.itexi @@ -135,7 +135,7 @@ METAFONT tutorial page}. PostScript is used to generate graphical output. A brief PostScript tutorial is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/, available online}. The -@uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Language +@uref{http://www.adobe.com/products/postscript/pdfs/PLRM.pdf, PostScript Language Reference} is available online in PDF format. @subsection Python @@ -979,7 +979,7 @@ for all errors and defines functions for displaying scheme objects (ps), grobs (pgrob), and parsed music expressions (pmusic). @example -file lily/out/lilypond +file $LILYPOND_GIT/build/out/bin/lilypond b programming_error b Grob::programming_error @@ -1311,6 +1311,10 @@ Regression tests should generally cover one issue per test. Several short, single-issue regression tests are preferred to a single, long, multiple-issue regression test. +If the change in the output is small or easy to overlook, use bigger +staff size -- 40 or more (up to 100 in extreme cases). Size 30 means +"pay extra attention to details in general". + Use existing regression tests as templates to demonstrate the type of header information that should be included in a regression test. @@ -1414,9 +1418,14 @@ Although it is not required, it is helpful if the developer can write relevant material for inclusion in the Notation Reference. If the developer does not feel qualified to write the documentation, a documentation editor will be able to -write it from the regression tests. The text that is added to -or removed from the documentation should be changed only in -the English version. +write it from the regression tests. In this case the developer +should raise a new issue with the Type=Documentation tag containing +a reference to the original issue number and/or the committish of +the pushed patch so that the need for new documention is not +overlooked. + +Any text that is added to or removed from the documentation should +be changed only in the English version. @node Edit changes.tely @@ -1449,7 +1458,7 @@ When these commands complete without error, the patch is considered to function successfully. Developers on Windows who are unable to build LilyPond should -get help from a Linux or OSX developer to do the make tests. +get help from a GNU/Linux or OSX developer to do the make tests. @node Verify regression tests @@ -1462,19 +1471,13 @@ introduced into the output. This process is described in @subheading Typical developer's edit/compile/test cycle -TODO: is @code{[-j@var{X} CPU_COUNT=@var{X}]} useful for -@code{test-baseline}, @code{check}, @code{clean}, -@code{test-redo}? Neil Puttock says it is useful for -everything but @code{clean}, which is disk-limited. -Need to check formally. - @itemize @item Initial test: @example make [-j@var{X}] -make test-baseline +make [-j@var{X} CPU_COUNT=@var{X}] test-baseline make [-j@var{X} CPU_COUNT=@var{X}] check @end example @@ -1484,10 +1487,10 @@ Edit/compile/test cycle: @example @emph{## edit source files, then...} -make clean @emph{## only if needed (see below)} -make [-j@var{X}] @emph{## only if needed (see below)} -make test-redo @emph{## redo files differing from baseline} -make [-j@var{X} CPU_COUNT=@var{X}] check @emph{## CPU_COUNT here?} +make clean @emph{## only if needed (see below)} +make [-j@var{X}] @emph{## only if needed (see below)} +make [-j@var{X} CPU_COUNT=@var{X}] test-redo @emph{## redo files differing from baseline} +make [-j@var{X} CPU_COUNT=@var{X}] check @end example @item @@ -1506,10 +1509,6 @@ the object files. If you only modify files which are interpreted, like those in the @file{scm/} and @file{ly/} directories, then @command{make} is not needed before @command{make test-redo}. -TODO: Fix the following paragraph. You can do @command{rm mf/out/*} -instead of make clean, and you can probably do -@command{make -C mf/ clean} as well, but I haven't checked it -- cds - Also, if you modify any font definitions in the @file{mf/} directory then you must run @command{make clean} and @command{make} before running @command{make test-redo}. This will @@ -1521,6 +1520,12 @@ Running @command{make@tie{}check} will leave an HTML page important differences that your change introduced, whether in the layout, MIDI, performance or error reporting. +You only need to use @command{make test-clean} to start from +scratch, prior to running @command{make@tie{}test-baseline}. To +check new modifications, all that is needed is to repeat +@command{make@tie{}test-redo} and @command{make@tie{}test-check} +(not forgetting @command{make} if needed). + @@ -1880,11 +1885,6 @@ slice of the spanner than considering it on the whole. This is useful during line breaking, for example, when we want to estimate the Y-extent of a spanner broken at given starting and ending columns. -If the pure function you're writing takes more than three arguments -(say, for example, a chained offset callback), this is not a problem: -just make sure that the grob is the first argument and that start and -end are the last two arguments. - @node How purity is defined and stored @subsection How purity is defined and stored @@ -2323,7 +2323,7 @@ classes because they play a special role in the linebreaking process. A C(++) object that is encapsulated so it can be used as a Scheme object. See GUILE info, "19.3 Defining New Types (Smobs)" -@@subheading When is each C++ class constructed and used +@subheading When is each C++ class constructed and used? @itemize