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).
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
@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
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 occurrences 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
@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.
@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?
There are two other derived classes System (derived from Spanner,
containing a "line of music") and Paper_column (derived from Item, it
-contains all items that happen at the same moment). They are separate
+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,
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
projects / lilypond.git / blobdiff