]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/contributor/programming-work.itexi
Fix white space
[lilypond.git] / Documentation / contributor / programming-work.itexi
index 34f33f49cec1c80fc584d828177342ef992cae27..6f3bbb824a6b4e505b57d51d1dea693069b55d21 100644 (file)
@@ -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 <reference SHA1 ID>
-@end example
-
-@noindent
-where <reference SHA1 ID> 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.