X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fprogramming-work.itexi;h=47c87132ef4dbb656413f9aa7c3bdf888f134c68;hb=29bd6abd1fdc4926f017d8c8825e3be72c6b0b85;hp=34f33f49cec1c80fc584d828177342ef992cae27;hpb=d7c0f4263534307616c82d9b2ce6fdef9472456f;p=lilypond.git diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi index 34f33f49ce..47c87132ef 100644 --- a/Documentation/contributor/programming-work.itexi +++ b/Documentation/contributor/programming-work.itexi @@ -48,7 +48,7 @@ music event is assigned a moment, or a time in the music when the event begins. Each type of music event has an associated iterator. Iterators are defined in -*-iterator.cc. During iteration, an +*-iterator.cc. During iteration, an event's iterator is called to deliver that music event to the appropriate context(s). @@ -131,12 +131,12 @@ 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 Lanugage +@uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Language Reference} is available online in PDF format. @subsection Python -Python is used for XML2ly and is used for buillding the documentation and the +Python is used for XML2ly and is used for building the documentation and the website. Python documentation is available at @uref{http://www.python.org/doc/, @@ -194,13 +194,13 @@ in the documentation. You can find these guidelines at When making changes or fixing bugs in LilyPond, one of the initial challenges is finding out where in the code tree the functions to be modified live. With nearly 3000 files in the source tree, -trial-and-error searching is generally ineffective. This section +trial-and-error searching is generally ineffective. This section describes a process for finding interesting code. @subsection Using the ROADMAP The file ROADMAP is located in the main directory of the lilypond source. -ROADMAP lists all of the directories in the LilPond source tree, along +ROADMAP lists all of the directories in the LilyPond source tree, along with a brief description of the kind of files found in each directory. This can be a very helpful tool for deciding which directories to search when looking for a function. @@ -317,7 +317,7 @@ The class Class_name is coded in @q{class-name.*} @node Indentation @subsection Indentation -Standard GNU coding style is used. In emacs: +Standard GNU coding style is used. In emacs: @verbatim (add-hook 'c++-mode-hook @@ -406,7 +406,7 @@ set number autocmd BufWritePre * :%s/\s\+$//e @end verbatim -With this .vimrc, files can be reindented automatically by highlihting +With this .vimrc, files can be reindented automatically by highlighting the lines to be indented in visual mode (use V to enter visual mode) and pressing =. @@ -416,19 +416,28 @@ was suggested by Patrick McCarty. It should be saved in @verbatim " Additional Guile-specific 'forms' -syn keyword schemeSyntax define-public define* define-safe-public +syn keyword schemeSyntax define-public define*-public +syn keyword schemeSyntax define* lambda* let-keywords* +syn keyword schemeSyntax defmacro defmacro* define-macro +syn keyword schemeSyntax defmacro-public defmacro*-public syn keyword schemeSyntax use-modules define-module -syn keyword schemeSyntax defmacro-public define-macro -syn keyword schemeSyntax define-markup-command -syn keyword schemeSyntax define-markup-list-command -syn keyword schemeSyntax let-keywords* lambda* define*-public -syn keyword schemeSyntax defmacro* defmacro*-public +syn keyword schemeSyntax define-method define-class + +" Additional LilyPond-specific 'forms' +syn keyword schemeSyntax define-markup-command define-markup-list-command +syn keyword schemeSyntax define-safe-public define-music-function +syn keyword schemeSyntax def-grace-function " All of the above should influence indenting too -set lw+=define-public,define*,define-safe-public,use-modules,define-module -set lw+=defmacro-public,define-macro +set lw+=define-public,define*-public +set lw+=define*,lambda*,let-keywords* +set lw+=defmacro,defmacro*,define-macro +set lw+=defmacro-public,defmacro*-public +set lw+=use-modules,define-module +set lw+=define-method,define-class set lw+=define-markup-command,define-markup-list-command -set lw+=let-keywords*,lambda*,define*-public,defmacro*,defmacro*-public +set lw+=define-safe-public,define-music-function +set lw+=def-grace-function " These forms should not influence indenting set lw-=if @@ -547,7 +556,7 @@ future. Even better would be to have an English (en_BR, en_AM) guide helping programmers writing consistent messages for all GNU programs. -Non-preferred messages are marked with `+'. By convention, +Non-preferred messages are marked with `+'. By convention, ungrammatical examples are marked with `*'. However, such ungrammatical examples may still be preferred. @@ -555,7 +564,7 @@ examples may still be preferred. @item Every message to the user should be localized (and thus be marked -for localization). This includes warning and error messages. +for localization). This includes warning and error messages. @item Do not localize/gettextify: @@ -584,10 +593,10 @@ warning (_ ("need music in a score")); error (_f ("cannot open file: `%s'", file_name)); @end example -In some rare cases you may need to call `gettext ()' by hand. This +In some rare cases you may need to call `gettext ()' by hand. This happens when you pre-define (a list of) string constants for later -use. In that case, you'll probably also need to mark these string -constants for translation, using `_i (STRING)'. The `_i' macro is +use. In that case, you'll probably also need to mark these string +constants for translation, using `_i (STRING)'. The `_i' macro is a no-op, it only serves as a marker for `xgettext'. @example @@ -607,7 +616,7 @@ foo (int i) See also `flower/getopt-long.cc' and `lily/main.cc'. @item -Do not use leading or trailing whitespace in messages. If you need +Do not use leading or trailing whitespace in messages. If you need whitespace to be printed, prepend or append it to the translated message @@ -624,7 +633,7 @@ foo.ly: 12: not a duration: 3 @end example Messages containing a final verb, or a gerund (`-ing'-form) always -start with a capital. Other (simpler) messages start with a +start with a capital. Other (simpler) messages start with a lowercase letter @example @@ -638,7 +647,7 @@ Avoid abbreviations or short forms, use `cannot' and `do not' rather than `can't' or `don't' To avoid having a number of different messages for the same situation, well will use quoting like this `"message: `%s'"' for all -strings. Numbers are not quoted: +strings. Numbers are not quoted: @example _f ("cannot open file: `%s'", name_str) @@ -646,9 +655,9 @@ _f ("cannot find character number: %d", i) @end example @item -Think about translation issues. In a lot of cases, it is better to -translate a whole message. The english grammar must not be imposed -on the translator. So, instead of +Think about translation issues. In a lot of cases, it is better to +translate a whole message. English grammar must not be imposed on the +translator. So, instead of @example stem at + moment.str () + does not fit in beam @@ -661,7 +670,7 @@ _f ("stem at %s does not fit in beam", moment.str ()) @end example @item -Split up multi-sentence messages, whenever possible. Instead of +Split up multi-sentence messages, whenever possible. Instead of @example warning (_f ("out of tune! Can't find: `%s'", "Key_engraver")); @@ -679,7 +688,7 @@ warning (_f ("Loading default font")); @item If you must have multiple-sentence messages, use full punctuation. -Use two spaces after end of sentence punctuation. No punctuation +Use two spaces after end of sentence punctuation. No punctuation (esp. period) is used at the end of simple messages. @example @@ -690,14 +699,14 @@ _f ("Huh? Not a Request: `%s'. Ignoring.", request) @item Do not modularize too much; words frequently cannot be translated -without context. It is probably safe to treat most occurences of +without context. It is probably safe to treat most occurrences of words like stem, beam, crescendo as separately translatable words. @item When translating, it is preferable to put interesting information at the end of the message, rather than embedded in the middle. This especially applies to frequently used messages, even if this -would mean sacrificing a bit of eloquency. This holds for original +would mean sacrificing a bit of eloquency. This holds for original messages too, of course. @example @@ -710,7 +719,7 @@ niet te openen: `foo.ly'* (3) The first nl message, although grammatically and stylistically correct, is not friendly for parsing by humans (even if they speak -dutch). I guess we would prefer something like (2) or (3). +dutch). I guess we would prefer something like (2) or (3). @item Do not run make po/po-update with GNU gettext < 0.10.35 @@ -783,7 +792,7 @@ out/bin/lilypond This is important as you will need to let gdb know where to find the image containing the symbol tables. You can invoke gdb from the -command line usinga the following: +command line using the following: @example gdb out/bin/lilypond @@ -1017,7 +1026,7 @@ performs in evaluating the procedure. @section Tracing object relationships Understanding the LilyPond source often boils down to figuring out what -is happening to the Grobs. Where (and why) are they being created, +is happening to the Grobs. Where (and why) are they being created, modified and destroyed? Tracing Lily through a debugger in order to identify these relationships can be time-consuming and tedious. @@ -1046,7 +1055,7 @@ number of different platforms: In order for the Graphviz tool to work, config.make must be modified. It is probably a good idea to first save a copy of config.make under -a different name. Then, edit config.make by removing every occurence +a different name. Then, edit config.make by removing every occurrence of @code{-DNDEBUG}. @item Rebuilding LilyPond @@ -1057,10 +1066,10 @@ The executable code of LilyPond must be rebuilt from scratch: make -C lily clean && make -C lily @end example -@item Create a graphviz-compatible .ly file +@item Create a graphviz-compatible @file{.ly} file -In order to use the graphviz utility, the .ly file must include -@file{ly/graphviz-init.ly}, and should then specify the +In order to use the graphviz utility, the @file{.ly} file must include +@file{ly/@/graphviz@/-init@/.ly}, and should then specify the grobs and symbols that should be tracked. An example of this is found in @file{input/regression/graphviz.ly}. @@ -1077,7 +1086,7 @@ lilypond graphviz.ly 2> graphviz.log The logfile has standard lilypond output, as well as the Graphviz output data. Delete everything from the beginning of the file -up to but not including the first occurence of @code{digraph}. +up to but not including the first occurrence of @code{digraph}. @item Process the logfile with @code{dot} @@ -1115,7 +1124,7 @@ for feature addition and modification. * Write the code:: * Write regression tests:: * Write convert-ly rule:: -* Automaticaly update auxiliary information:: +* Automatically update auxiliary information:: * Manually update auxiliary information:: * Edit changes.tely:: * Verify successful build:: @@ -1168,8 +1177,21 @@ of the file. In some cases, this will not be possible, so the rule will simply point out to the user that the feature needs manual correction. +@subsubheading Updating version numbers + +If a development release occurs between you writing your patch and +having it approved+pushed, you will need to update the version +numbers in your tree. This can be done with: + +@example +scripts/auxiliar/update-patch-version old.version.number new.version.number +@end example + +It will change all files in git, so use with caution and examine +the resulting diff. + -@node Automaticaly update auxiliary information +@node Automatically update auxiliary information @subsection Automatically update auxiliary information convert-ly should be used to update the documentation, the snippets, @@ -1354,7 +1376,7 @@ recompile everything, whether modified or not, and takes a lot longer. Running @command{make@tie{}check} will leave an HTML page -@file{out/test-results/index.html}. This page shows all the +@file{out/@/test@/-results/@/index@/.html}. This page shows all the important differences that your change introduced, whether in the layout, MIDI, performance or error reporting. @@ -1419,6 +1441,8 @@ patch set will be posted to Rietveld. You should then announce the patch by sending an email to lilypond-devel, with a subject line starting with PATCH:, asking for comments on the patch. +Alternately, you may Publish + Mail a (bogus) comment, in order +to send an email to lilypond-devel. As revisions are made in response to comments, successive patch sets for the same issue can be uploaded by reissuing the git-cl command @@ -1426,7 +1450,7 @@ with the modified branch checked out. Sometimes in response to comments on revisions, the best way to work may require creation of a new branch in git. In order to -associate the new branch with an existing Reitveld issue, +associate the new branch with an existing Rietveld issue, the following command can be used: @example @@ -1678,7 +1702,7 @@ TODO -- This is a placeholder for a tutorial on callback functions. @node LilyPond scoping @section LilyPond scoping -The Lilypond language has a concept of scoping, ie you can do +The Lilypond language has a concept of scoping, i.e. you can do @example foo = 1 @@ -1749,7 +1773,7 @@ pipeline, is it not too late?? Joe Neeman answered: We create lots of extra grobs (eg. a BarNumber at every bar line) but -most of them are not drawn. See the break-visibility property in +most of them are not drawn. See the break-visibility property in item-interface. @@ -1766,7 +1790,7 @@ the body text are Han-Wen's answers. @subheading Figuring out how things work. I must admit that when I want to know how a program works, I use grep -and emacs and dive into the source code. The comments and the code +and emacs and dive into the source code. The comments and the code itself are usually more revealing than technical documents. @subheading What's a grob, and how is one used? @@ -1776,8 +1800,8 @@ Spanners (derived class) -slurs, beams- or Items (also a derived class) -notes, clefs, etc. There are two other derived classes System (derived from Spanner, -contaning a "line of music") and Paper_column (derived from Item, it -contains all items that happen at the same moment). They are separate +containing a "line of music") and Paper_column (derived from Item, it +contains all items that happen at the same moment). They are separate classes because they play a special role in the linebreaking process. @subheading What's a smob, and how is one used? @@ -1803,7 +1827,7 @@ Constructed during "interpreting" phase. Engravers Executive branch of Contexts, plugins that create grobs, usually one -engraver per grob type. Created together with context. +engraver per grob type. Created together with context. @item Layout Objects @@ -1813,9 +1837,9 @@ Layout Objects @item Grob Interfaces -These are not C++ classes per se. The idea of a Grob interface hasn't -crystallized well. ATM, an interface is a symbol, with a bunch of grob -properties. They are not objects that are created or destroyed. +These are not C++ classes per se. The idea of a Grob interface hasn't +crystallized well. ATM, an interface is a symbol, with a bunch of grob +properties. They are not objects that are created or destroyed. @item Iterators @@ -1834,20 +1858,20 @@ BTW, the entry point for interpreting is ly:run-translator @subheading Can you get to Context properties from a Music object? You can create music object with a Scheme function that reads context -properties (the \applycontext syntax). However, that function is +properties (the \applycontext syntax). However, that function is executed during Interpreting, so you can not really get Context properties from Music objects, since music objects are not directly -connected to Contexts. That connection is made by the Music_iterators +connected to Contexts. That connection is made by the Music_iterators @subheading Can you get to Music properties from a Context object? Yes, if you are given the music object within a Context -object. Normally, the music objects enter Contexts in synchronized +object. Normally, the music objects enter Contexts in synchronized fashion, and the synchronization is done by Music_iterators. @subheading What is the relationship between C++ classes and Scheme objects? -Smobs are C++ objects in Scheme. Scheme objects (lists, functions) are +Smobs are C++ objects in Scheme. Scheme objects (lists, functions) are manipulated from C++ as well using the GUILE C function interface (prefix: scm_) @@ -1864,11 +1888,11 @@ Export a C++ function to Scheme with LY_DEFINE. Good question. Things used to be clear-cut, but we have Scheme and SMOBs now, which means that interactions do not follow a very -rigid format anymore. See below for an overview, though. +rigid format anymore. See below for an overview, though. @subheading Does the parser make Scheme procedure calls or C++ function calls? -Both. And the Scheme calls can call C++ and vice versa. It's nested, +Both. And the Scheme calls can call C++ and vice versa. It's nested, with the SCM datatype as lubrication between the interactions (I think the word "lubrication" describes the process better than the @@ -1876,7 +1900,7 @@ traditional word "glue") @subheading How do the front-end and back-end get started? -Front-end: a file is parsed, the rest follows from that. Specifically, +Front-end: a file is parsed, the rest follows from that. Specifically, Parsing leads to a Music + Music_output_def object (see parser.yy, definition of toplevel_expression ) @@ -1885,15 +1909,15 @@ A Music + Music_output_def object leads to a Global_context object (see ly_run_translator ()) During interpreting, Global_context + Music leads to a bunch of -Contexts. (see Global_translator::run_iterator_on_me () ) +Contexts (see Global_translator::run_iterator_on_me ()). After interpreting, Global_context contains a Score_context (which -contains staves, lyrics etc.) as a child. Score_context::get_output () +contains staves, lyrics etc.) as a child. Score_context::get_output () spews a Music_output object (either a Paper_score object for notation or Performance object for MIDI). -The Music_output object is the entry point for the backend. (see -ly_render_output () ) +The Music_output object is the entry point for the backend (see +ly_render_output ()). The main steps of the backend itself are in @@ -1915,14 +1939,14 @@ to produce TeX and PS. @end itemize Interactions between grobs and putting things into .tex and .ps files -have gotten a little more complex lately. Jan has implemented +have gotten a little more complex lately. Jan has implemented page-breaking, so now the backend also involves Paper_book, -Paper_lines and other things. This area is still heavily in flux, and +Paper_lines and other things. This area is still heavily in flux, and perhaps not something you should want to look at. @subheading How do the front-end and back-end communicate? -There is no communication from backend to front-end. From front-end to +There is no communication from backend to front-end. From front-end to backend is simply the program flow: music + definitions gives contexts, contexts yield output, after processing, output is written to disk. @@ -1949,7 +1973,7 @@ Music_iterators can set and read context properties, idem for Engravers and Contexts Music_iterators can send "synthetic" music events (which aren't in -the input) to a context. These are caught by Engravers. This is +the input) to a context. These are caught by Engravers. This is mostly a one way communication channel. part-combine-status is part of such a synthetic event, used by @@ -1964,14 +1988,14 @@ procedure has a Music argument. Does this mean I should use a Music property? \autochange is one of these extra strange beasts: it requires -look-ahead to decide when to change staves. This is achieved by +look-ahead to decide when to change staves. This is achieved by running the interpreting step twice (see scm/part-combiner.scm , at the bottom), and storing the result of the first step (where to switch staves) in a Music property. Since you want to influence that where-to-switch list, your must affect the code in -make-autochange-music (scm/part-combiner.scm). That code is called +make-autochange-music (scm/part-combiner.scm). That code is called directly from the parser and there are no official "parsing -properties" yet, so there is no generic way to tune \autochange. We +properties" yet, so there is no generic way to tune \autochange. We would have to invent something new for this, or add a separate argument, @@ -2056,8 +2080,8 @@ while to figure that out, and I still didn't know who did the calling in the first place. I only know a little bit about Flex and Bison, so reading those files helped only a little bit. -@emph{Han-Wen:} GDB can be of help here. Set a breakpoint in C++, and run. When you -hit the breakpoint, do a backtrace. You can inspect Scheme objects +@emph{Han-Wen:} GDB can be of help here. Set a breakpoint in C++, and run. When you +hit the breakpoint, do a backtrace. You can inspect Scheme objects along the way by doing @example @@ -2105,7 +2129,7 @@ finds out about the breakpoint. Han-Wen answered as follows: -You can see the defintion by doing +You can see the definition by doing @example #(display conditionalMark)