From d3dbdfb4a33205cfed5478e22cf98665622c5901 Mon Sep 17 00:00:00 2001 From: Carl Sorensen Date: Fri, 16 Jan 2009 15:47:06 -0700 Subject: [PATCH] Doc: Update Contributors Guide Add information from README-devel.txt to CG. Proofreading and minor changes on documentation standards --- Documentation/devel/doc-work.itexi | 23 ++-- Documentation/devel/programming-work.itexi | 130 +++++++++++++++++++-- 2 files changed, 133 insertions(+), 20 deletions(-) diff --git a/Documentation/devel/doc-work.itexi b/Documentation/devel/doc-work.itexi index f717db48a9..5dfef1d625 100644 --- a/Documentation/devel/doc-work.itexi +++ b/Documentation/devel/doc-work.itexi @@ -701,7 +701,7 @@ Both index commands should go in front of the actual material. 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 @@ -723,7 +723,7 @@ List of specific terms: @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 @@ -755,12 +755,11 @@ Do not explicitly refer to the reader/user. There is no one else 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,} @@ -783,7 +782,7 @@ time. For each subsection, @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. @@ -850,7 +849,13 @@ possible into there. 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 diff --git a/Documentation/devel/programming-work.itexi b/Documentation/devel/programming-work.itexi index 24741412fa..4d36a21fbf 100644 --- a/Documentation/devel/programming-work.itexi +++ b/Documentation/devel/programming-work.itexi @@ -3,7 +3,9 @@ @chapter Programming work @menu -* Introduction to programming:: +* Introduction to programming:: +* Programming without compiling:: +* Finding functions:: * Code style:: @end menu @@ -13,6 +15,111 @@ 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 @@ -21,7 +128,7 @@ blah blah @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 @@ -128,24 +235,25 @@ Messages need to follow Localization. @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 @@ -279,7 +387,7 @@ Use two spaces after end of sentence punctuation. No punctuation @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. -- 2.39.2