is preferred instead of @qq{Time signature}, Only use capital
letters for musical terms which demand them, like D.S. al Fine.
-For scheme functions, only include the final part, ie
+For scheme functions, only include the final part, i.e.,
@example
@@funindex modern-voice-cautionary
@example
canceled
-simultaenous NOT concurrent
+simultaneous NOT concurrent
measure: the unit of music
bar line: the symbol delimiting a measure NOT barline
note head NOT notehead
besides the reader and the writer.
@item
-Do not use abbreviations (don't, won't, etc.). If you do, use a
-comma after it:
+Avoid contractions (don't, won't, etc.). Spell the words out completely.
-@example
-blabla blabla, i.e., blabla blabla
-@end example
+@item
+Avoid abbreviations, except for commonly used abbreviations of foreign
+language terms such as etc. and i.e.
@item
Avoid fluff (@qq{Notice that,} @qq{as you can see,}
@item
check the mundane formatting. Are the headings (@@predefined,
-@@seealso, etc) in the right order?
+@@seealso, etc.) in the right order?
@item
add any appropriate index entries.
It would be @qq{nice} if you spent a lot of time crafting nice
tweaks for users... but my recommendation is @strong{not} to do
this. There's a lot of doc work to do without adding examples of
-tweaks. Tweak examples are trivial to added by normal users.
+tweaks. Tweak examples can easily be added by normal users by adding
+them to the LSR.
+
+One place where a documentation writer can profitably spend time writing
+or upgrading tweaks is creating tweaks to deal with known issues. It
+would be ideal if every significant known issue had a workaround to avoid
+the difficulty.
@node Updating docs with convert-ly
@chapter Programming work
@menu
-* Introduction to programming::
+* Introduction to programming::
+* Programming without compiling::
+* Finding functions::
* Code style::
@end menu
blah blah
+@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
+changes are described in this section.
+
+
+@subsection Modifying distribution files
+
+Mving uch 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
+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.
+
+Once you've modified the files, you can test the changes just by running
+LilyPond on some input file. It's a good idea to create a file that
+demonstrates the feature you're trying to add. This file will eventually
+become a regression test and will be part of the LilyPond distribution.
+
+@subsection Desired file formatting
+
+Files that are part of the LilyPond distribution have Unix-style line
+endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
+sure you use the necessary tools ensure that Unix-style line endings are
+preserved in the patches you create.
+
+Tab characters should not be included in files for distribution. All
+indentation should be done with spaces. Most editors have settings to
+allow the setting of tab stops and ensuring that no tab characters are
+included in the file.
+
+@node Finding functions
+@section Finding functions
+
+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 inefective. 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
+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.
+
+
+@subsection Using grep to search
+
+Having identified a likely subdirectory to search, the grep utility can
+be used to search for a function name. The format of the grep command is
+
+@example
+grep functionName subdirectory/*
+@end example
+
+This command will search all the contents of the directory subdirectory/
+and display every line in any of the files that contains functionName.
+
+THe most likely directories to grep for function names are scm/ for
+scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
+files.
+
+
+@subsection Using git grep to search
+
+If you have used git to obtain the source, you have access to a
+powerful tool to search for functions. The command:
+
+@example
+git grep functionName
+@end example
+
+will search through all of the files that are present in the git
+repository looking for functionName. It also presents the results
+of the search using @code{less}, so the results are displayed one page
+at a time.
+
+@subsection Searching on the git repository at Savannah
+
+You can also use the equivalent of git grep on the Savannah server.
+
+@itemize
+
+@item
+Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
+
+@item
+In the pulldown box that says commit, select grep.
+
+@item
+Type functionName in the search box, and hit enter/return
+
+@end itemize
+
+This will initiate a search of the remote git repository.
+
+
@node Code style
@section Code style
@menu
@end menu
-@subsection Outputting errors
+@subsection Handling errors
As a general rule, you should always try to continue computations,
even if there is some kind of error. When the program stops, it
@subsection Localization
This document provides some guidelines for programmers write user
-messages. To help translations, user messages must be
-uniformized. Follow these rules when coding for LilyPond.
+messages. To help translations, user messages must follow
+uniform conventions. Follow these rules when coding for LilyPond.
Hopefully, this can be replaced by general GNU guidelines in the
future. Even better would be to have an English (en_BR, en_AM)
-helping programmers writing consistent messages for all GNU
+guide helping programmers writing consistent messages for all GNU
programs.
-Not-preferred messages are marked with `+'. By convention,
-ungrammatical examples are marked with `*'.
+Non-preferred messages are marked with `+'. By convention,
+ungrammatical examples are marked with `*'. However, such ungrammatical
+examples may still be preferred.
@itemize
@item
-Every message to the user should be localised (and thus be marked
-for localisation). This includes warning and error messages.
+Every message to the user should be localized (and thus be marked
+for localization). This includes warning and error messages.
@item
-Don't localise/gettextify:
+Don't localize/gettextify:
@itemize
@item
@end verbatim
@item
-Do not modularise too much; a lot of words cannot be translated
+Do not modularise too much; words frequently cannot be translated
without context. It's probably safe to treat most occurences of
words like stem, beam, crescendo as separately translatable words.
projects / lilypond.git / commitdiff