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).
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/,
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.
@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
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 =.
@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
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.
@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:
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
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
@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
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)
@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
@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"));
@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
@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
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
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
@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.
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
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}.
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}
* 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::
manual correction.
-@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,
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.
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
@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
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.
@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?
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?
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
@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
@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_)
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
@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 )
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
@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.
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
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,
where around-central-C is some function that is called from
make-autochange-music.
+@subheading More on context and music properties
+
+From Neil Puttock, in response to a question about transposition:
+
+Context properties (using \set & \unset) are tied to engravers: they
+provide information relevant to the generation of graphical objects.
+
+Since transposition occurs at the music interpretation stage, it has
+no direct connection with engravers: the pitch of a note is fixed
+before a notehead is created. Consider the following minimal snippet:
+
+@example
+@{ c' @}
+@end example
+
+This generates (simplified) a NoteEvent, with its pitch and duration
+as event properties,
+
+@example
+(make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 0 0)
+@end example
+
+which the Note_heads_engraver hears. It passes this information on to
+the NoteHead grob it creates from the event, so the head's correct
+position and duration-log can be determined once it's ready for
+printing.
+
+If we transpose the snippet,
+
+@example
+\transpose c d @{ c' @}
+@end example
+
+the pitch is changed before it reaches the engraver (in fact, it
+happens just after the parsing stage with the creation of a
+TransposedMusic music object):
+
+@example
+(make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 1 0)
+@end example
+
+You can see an example of a music property relevant to transposition:
+untransposable.
+
+@example
+\transpose c d @{ c'2 \withMusicProperty #'untransposable ##t c' @}
+@end example
+
+-> the second c' remains untransposed.
+
+Take a look at lily/music.cc to see where the transposition takes place.
+
+
@subheading How do I tell about the execution environment?
I get lost figuring out what environment the code I'm looking at is in when it
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
Han-Wen answered as follows:
-You can see the defintion by doing
+You can see the definition by doing
@example
#(display conditionalMark)
projects / lilypond.git / blobdiff