X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fprogramming-work.itexi;h=6f3bbb824a6b4e505b57d51d1dea693069b55d21;hb=24bcb253054634563f444440ea38443349c14355;hp=34f33f49cec1c80fc584d828177342ef992cae27;hpb=1c122290caffd067b81c60a18c97e61d1c6b209e;p=lilypond.git diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi index 34f33f49ce..6f3bbb824a 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 +@file{*-iterator.cc}. During iteration, an event's iterator is called to deliver that music event to the appropriate context(s). @@ -58,7 +58,8 @@ translation step is accomplished by the polymorphic base class Translator through its two derived classes: Engraver (for graphical output) and Performer (for midi output). -Translators are defined in C++ files named *-engraver.cc and *-performer.cc. +Translators are defined in C++ files named @file{*-engraver.cc} +and @file{*-performer.cc}. Much of the work of translating is handled by Scheme functions, which is one of the keys to LilyPond's exceptional flexibility. @@ -131,12 +132,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/, @@ -145,8 +146,8 @@ python.org}. @node Programming without compiling @section Programming without compiling -Much of the development work in LilyPond takes place by changing *.ly or -*.scm files. These changes can be made without compiling LilyPond. Such +Much of the development work in LilyPond takes place by changing @file{*.ly} or +@file{*.scm} files. These changes can be made without compiling LilyPond. Such changes are described in this section. @@ -155,8 +156,8 @@ changes are described in this section. Much of LilyPond is written in Scheme or LilyPond input files. These files are interpreted when the program is run, rather than being compiled when the program is built, and are present in all LilyPond distributions. -You will find .ly files in the ly/ directory and the Scheme files in the -scm/ directory. Both Scheme files and .ly files can be modified and +You will find @file{.ly} files in the @file{ly/} directory and the Scheme files in the +@file{scm/} directory. Both Scheme files and @file{.ly} files can be modified and saved with any text editor. It's probably wise to make a backup copy of your files before you modify them, although you can reinstall if the files become corrupted. @@ -194,13 +195,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. @@ -221,8 +222,8 @@ functionName. The @code{-i} option makes @command{grep} ignore case -- this can be very useful if you are not yet familiar with our capitalization conventions. -The most likely directories to grep for function names are scm/ for -scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++ +The most likely directories to grep for function names are @file{scm/} for +scheme files, ly/ for lilypond input (@file{*.ly}) files, and @file{lily/} for C++ files. @@ -317,7 +318,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 @@ -351,7 +352,7 @@ on a c++ file: scripts/auxiliar/fixcc.py lily/my-test-file.cc @end example -Be sure you replace @code{my-test-file.cc} with the name of the file +Be sure you replace @file{my-test-file.cc} with the name of the file that you edited. If you are editing a file that contains an ADD_TRANSLATOR or ADD_INTERFACE @@ -406,7 +407,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 +417,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 +557,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 +565,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 +594,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 @@ -604,10 +614,10 @@ foo (int i) @} @end example -See also `flower/getopt-long.cc' and `lily/main.cc'. +See also @file{flower/getopt-long.cc} and @file{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 +634,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 +648,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 +656,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 +671,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 +689,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 +700,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 +720,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,14 +793,14 @@ 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 @end example @noindent This loads the LilyPond symbol tables into gdb. Then, to run -LilyPond on @code{test.ly} under the debugger, enter the following: +LilyPond on @file{test.ly} under the debugger, enter the following: @example run test.ly @@ -856,21 +866,21 @@ environment, it is necessary to have a Guile interpreter that has all the LilyPond modules loaded. This requires the following steps. -First, define a Scheme symbol for the active module in the .ly file: +First, define a Scheme symbol for the active module in the @file{.ly} file: @example #(module-define! (resolve-module '(guile-user)) 'lilypond-module (current-module)) @end example -Now place a Scheme function in the .ly file that gives an +Now place a Scheme function in the @file{.ly} file that gives an interactive Guile prompt: @example #(top-repl) @end example -When the .ly file is compiled, this causes the compilation to be +When the @file{.ly} file is compiled, this causes the compilation to be interrupted and an interactive guile prompt to appear. Once the guile prompt appears, the LilyPond active module must be set as the current guile module: @@ -906,7 +916,7 @@ interpreter can be exited: guile> (quit) @end example -The compilation of the .ly file will then continue. +The compilation of the @file{.ly} file will then continue. @subheading Using the Guile debugger @@ -959,7 +969,7 @@ breakpoint will be set straight after you enter the @code{(quit)} command at the guile prompt. Embedding breakpoint commands like this is particularly useful if -you want to look at how the Scheme procedures in the @var{.scm} +you want to look at how the Scheme procedures in the @file{.scm} files supplied with LilyPond work. To do this, edit the file in the relevant directory to add this line near the top: @@ -969,7 +979,7 @@ the relevant directory to add this line near the top: Now you can set a breakpoint after the procedure you are interested in has been declared. For example, if you are working on routines -called by @var{print-book-with} in @var{lily-library.scm}: +called by @var{print-book-with} in @file{lily-library.scm}: @example (define (print-book-with parser book process-procedure) @@ -1017,7 +1027,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 +1056,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,9 +1067,9 @@ 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 +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 +1087,10 @@ 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}. + +Also, delete the final liypond message about successs from the end +of the file. @item Process the logfile with @code{dot} @@ -1115,8 +1128,8 @@ for feature addition and modification. * Write the code:: * Write regression tests:: * Write convert-ly rule:: -* Automaticaly update auxiliary information:: -* Manually update auxiliary information:: +* Automatically update documentation:: +* Manually update documentation:: * Edit changes.tely:: * Verify successful build:: * Verify regression tests:: @@ -1141,7 +1154,7 @@ earlier in this chapter. In order to demonstrate that the code works properly, you will need to write one or more regression tests. These tests are -typically .ly files that are found in input/regression. +typically @file{.ly} files that are found in @file{input/regression}. Regression tests should be as brief as possible to demonstrate the functionality of the code. @@ -1168,42 +1181,44 @@ 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 -@node Automaticaly update auxiliary information -@subsection Automatically update auxiliary information - -convert-ly should be used to update the documentation, the snippets, -and the regression tests. This not only makes the necessary syntax -changes, it also tests the convert-ly rules. - -The automatic updating is a three step process. First, be sure you -are in the top-level source directory. Then, for the -documentation, do: +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 -find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}} +scripts/auxiliar/update-patch-version old.version.number new.version.number @end example -@noindent -where @var{X.Y.Z} is the version number of the last released development -version. +It will change all files in git, so use with caution and examine +the resulting diff. -Next, for the snippets, do: + +@node Automatically update documentation +@subsection Automatically update documentation + +@command{convert-ly} should be used to update the documentation, +the snippets, and the regression tests. This not only makes the +necessary syntax changes, it also tests the @command{convert-ly} +rules. + +The automatic updating is performed by moving to the top-level +source directory, then running: @example -find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}} +scripts/auxiliar/update-with-convert-ly.sh @end example -Finally, for the regression tests, do: +If you did an out-of-tree build, pass in the relative path: @example -find input/regression/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}} - +BUILD_DIR=../build-lilypond/ scripts/auxiliar/update-with-convert-ly.sh @end example -@node Manually update auxiliary information -@subsection Manually update auxiliary information +@node Manually update documentation +@subsection Manually update documentation Where the convert-ly rule is not able to automatically update the inline lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the @@ -1295,7 +1310,7 @@ get help from a Linux or OSX developer to do the make tests. In order to avoid breaking LilyPond, it is important to verify that the regression tests succeed, and that no unwanted changes are introduced into the output. This process is described in -@ref{Identifying code regressions}. +@ref{Regtest comparison}. @subheading Typical developer's edit/compile/test cycle @@ -1364,79 +1379,7 @@ layout, MIDI, performance or error reporting. @node Post patch for comments @subsection Post patch for comments -For any change other than a minor change, a patch set should be -posted on @uref{http://codereview.appspot.com/, Rietveld} for comment. -This requires the use of an external package, git-cl, and an email -account on Google. - -git-cl is installed by: - -@example -git clone git://neugierig.org/git-cl.git -@end example - -Then, add the git-cl directory to your PATH, or create a -symbolic link to the git-cl and upload.py in one of your -PATH directories (like usr/bin). git-cl is then -configured by entering the command - -@example -git cl config -@end example - -@noindent -in the LilyPond git directory and answering the questions that -are asked. If you do not understand the question answer with just -a newline (CR). - -The patch set is posted to Rietveld as follows. Ensure your changes -are committed in a separate branch, which should differ from the -reference branch to be used by just the changes to be uploaded. -If the reference branch is to be origin/master, ensure this is -up-to-date. If necessary, use git rebase to rebase the branch -containing the changes to the head of origin/master. Finally, -check out branch with the changes and enter the command: - -@example -git cl upload -@end example - -@noindent -where is the SHA1 ID of the commit to be used -as a reference source for the patch. Generally, this will be the -SHA1 ID of origin/master, and in that case the command - -@example -git cl upload origin/master -@end example - -@noindent -can be used. - -After prompting for your Google email address and password, the -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. - -As revisions are made in response to comments, successive patch sets -for the same issue can be uploaded by reissuing the git-cl command -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, -the following command can be used: - -@example -git cl issue issue-number -@end example - -@noindent -where @code{issue-number} is the number of the existing Rietveld -issue. - +See @ref{Uploading a patch for review}. @node Push patch @@ -1678,7 +1621,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 +1692,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 +1709,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 +1719,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 +1746,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 +1756,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 +1777,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 +1807,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 +1819,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,59 +1828,59 @@ 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 @itemize @item -paper-score.cc , Paper_score::process_ +@file{paper-score.cc} , Paper_score::process_ @item -system.cc , System::get_lines() +@file{system.cc} , System::get_lines() @item The step, where things go from grobs to output, is in System::get_line(): each grob delivers a Stencil (a Device independent output description), which is interpreted by our -outputting backends (scm/output-tex.scm and scm/output-ps.scm) -to produce TeX and PS. +outputting backends (@file{scm/output-tex.scm} and +@file{scm/output-ps.scm}) 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. @subheading Where is the functionality associated with KEYWORDs? -See my-lily-lexer.cc (keywords, there aren't that many) and ly/*.ly -(most of the other backslashed \words are identifiers) +See @file{my-lily-lexer.cc} (keywords, there aren't that many) +and @file{ly/*.ly} (most of the other backslashed @code{/\words} are identifiers) @subheading What Contexts/Properties/Music/etc. are available when they are processed? What do you mean exactly with this question? -See ly/engraver-init.ly for contexts, see scm/define-*.scm for other -objects. +See @file{ly/engraver-init.ly} for contexts, +see @file{scm/define-*.scm} for other objects. @subheading How do you decide if something is a Music, Context, or Grob property? Why is part-combine-status a Music property when it seems (IMO) @@ -1949,7 +1892,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,16 +1907,17 @@ 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 -running the interpreting step twice (see scm/part-combiner.scm , at -the bottom), and storing the result of the first step (where to switch +look-ahead to decide when to change staves. This is achieved by +running the interpreting step twice (see +@file{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 -directly from the parser and there are no official "parsing -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, +make-autochange-music (@file{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 would have to invent something new +for this, or add a separate argument, @example \autochange #around-central-C ..music.. @@ -2043,7 +1987,7 @@ untransposable. -> the second c' remains untransposed. -Take a look at lily/music.cc to see where the transposition takes place. +Take a look at @file{lily/music.cc} to see where the transposition takes place. @subheading How do I tell about the execution environment? @@ -2056,8 +2000,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,16 +2049,16 @@ 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) @end example noindent -inside the .ly file. +inside the @file{.ly} file. The breakpoint failing may have to do with the call sequence. See -parser.yy, run_music_function(). The function is called directly from +@file{parser.yy}, run_music_function(). The function is called directly from C++, without going through the GUILE evaluator, so I think that is why there is no debugger trap.