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).
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.
@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.
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.
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.
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
@}
@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
@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
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:
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
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:
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)
@item Create a graphviz-compatible @file{.ly} file
In order to use the graphviz utility, the @file{.ly} file must include
-@file{ly/@/graphviz@/-init@/.ly}, and should then specify the
+@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}.
output data. Delete everything from the beginning of the file
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}
The directed graph is created from the log file with the program
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.
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
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.
@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
@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)
\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
+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..
-> 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?
@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.
projects / lilypond.git / blobdiff