Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.16.0"
@node Suggestions for writing files
@chapter Suggestions for writing files
@node General suggestions
@section General suggestions
-Here are a few suggestions that can help you to avoid or fix
-problems:
+Here are a few suggestions that can help to avoid (and fix) the most
+common problems when typesetting:
@itemize
-@item @strong{Include @code{\version} numbers in every file}. Note that all
-templates contain @code{\version} information. We
-highly recommend that you always include the @code{\version}, no matter
-how small your file is. Speaking from personal experience, it's
-quite frustrating to try to remember which version of LilyPond you were
-using a few years ago. @command{convert-ly} requires you to declare
-which version of LilyPond you used.
-
-@item @strong{Include checks}: @ruser{Bar and bar number checks},
-@ruser{Octave checks}. If you include checks every so often, then
-if you make a mistake, you can pinpoint it quicker. How often is
-@q{every so often}? It depends on the complexity of the music.
-For very simple music, perhaps just once or twice. For very
-complex music, perhaps every bar.
-
-@item @strong{One bar per line of text}. If there is anything complicated,
-either in the music
-itself or in the output you desire, it's often good to write only one bar
-per line. Saving screen space by cramming eight bars per line just isn't
-worth it if you have to @q{debug} your input files.
-
-@item @strong{Comment your input files}. Use either bar numbers
-(every so often) or
-references to musical themes (@q{second theme in violins,} @q{fourth
-variation,} etc.). You may not need comments when you're writing the piece
-for the first time, but if you want to go back to change something two or
-three years later, or if you pass the source over to a friend, it will
-be much more
-challenging to determine your intentions or how your file is structured if
-you didn't comment the file.
-
-@item @strong{Indent your braces}. A lot of problems are caused by an
-imbalance
-in the number of @code{@{} and @code{@}}.
-
-@item @strong{Explicitly add durations} at the beginnings of sections
-and variables. If you specify @code{c4 d e} at the beginning of a
-phrase (instead of just @code{c d e}) you can save yourself some
-problems if you rearrange your music later.
-
-@item @strong{Separate tweaks} from music definitions. See
+@item
+@strong{Always include a @code{\version} number in your input files} no
+matter how small they are. This prevents having to remember which
+version of LilyPond the file was created with and is especially relevant
+when @ref{Updating files with convert-ly} command (which requires the
+@code{\version} statement to be present); or if sending your input files
+to other users (e.g. when asking for help on the mail lists). Note that
+all of the LilyPond templates contain @code{\version} numbers.
+
+@item
+@strong{For each line in your input file, write one bar of music}. This
+will make debugging any problems in your input files much simpler.
+
+@item
+@strong{Include @ruser{Bar and bar number checks} as well as
+@ruser{Octave checks}}. Including @q{checks} of this type in your input
+files will help pinpoint mistakes more quickly. How often checks are
+added will depend on the complexity of the music being typeset. For
+simple compositions, checks added at a few at strategic points within
+the music can be enough but for more complex music, with many voices
+and/or staves, checks may be better placed after every bar.
+
+@item
+@strong{Add comments within input files}. References to musical themes
+(i.e. @q{second theme in violins}, @q{fourth variation,} etc.), or
+simply including bar numbers as comments, will make navigating the input
+file much simpler especically if something needs to be altered later
+on or if passing on LilyPond input files to another person.
+
+@item
+@strong{Add explicit note durations at the start of @q{sections}}. For
+example, @code{c4 d e f} instead of just @code{c d e f} can make
+rearranging the music later on simpler.
+
+@item
+@strong{Learn to indent and align braces and parallel music}. Many
+problems are often caused by either @q{missing} braces. Clearly
+indenting @q{opening} and @q{closing} braces (or @code{<<} and @code{>>}
+indicators) will help avoid such problems. For example;
+
+@example
+\new Staff @{
+ \relative g' @{
+ r4 g8 g c8 c4 d |
+ e4 r8 |
+ % Ossia section
+ <<
+ @{ f8 c c | @}
+ \new Staff @{
+ f8 f c |
+ @}
+ >>
+ r4 |
+ @}
+@}
+@end example
+
+@noindent
+is much easier to follow than;
+
+@example
+\new Staff @{ \relative g' @{ r4 g8 g c4 c8 d | e4 r8
+% Ossia section
+<< @{ f8 c c @} \new Staff @{ f8 f c @} >> r4 | @} @}
+@end example
+
+
+@item
+@strong{Keep music and style separate} by putting overrides in the
+@code{\layout} block;
+
+@example
+\score @{
+ @var{@dots{}music@dots{}}
+ \layout @{
+ \override TabStaff.Stemstencil = ##f
+ @}
+@}
+@end example
+
+This will not create a new context but it will apply when one is
+created. Also see
@rlearning{Saving typing with variables and functions}, and
@rlearning{Style sheets}.
variable, it is recommended that the notes are wrapped in
@example
-\transpose c natural-pitch @{...@}
+\transpose c natural-pitch @{@dots{}@}
@end example
@noindent
violin = \relative c'' @{
g4 c'8. e16
@}
-...
+@dots{}
\score @{
\new GrandStaff @{
\new Staff @{
@}
@end example
-@item @strong{Separate tweaks from music definitions}. This
-point was made previously, but for large
-projects it is absolutely vital. We might need to change
-the definition of @code{fthenp}, but then we only need
-to do this once, and we can still avoid touching anything
-inside @code{violin}.
+@item @strong{Separate tweaks from music definitions}. This point was
+made previously, but for large projects it is absolutely vital. We
+might need to change the definition of @code{fthenp}, but then we only
+need to do this once, and we can still avoid touching anything inside
+@code{violin}.
@example
fthenp = _\markup@{
The most powerful tools for this purpose are the
single line comment (indicated by @code{%}) and the block
-comment (indicated by @code{%@{ ... %@}}). If you don't
+comment (indicated by @code{%@{@dots{}%@}}). If you don't
know where a problem is, start commenting out huge portions
of your input file. After you comment out a section, try
compiling the file again. If it works, then the problem
@cindex make
Pretty well all the platforms Lilypond can run on support a software
-facility called @code{make}. This software reads a special file called a
+facility called @code{make}. This software reads a special file called a
@code{Makefile} that defines what files depend on what others and what
commands you need to give the operating system to produce one file from
-another. For example the makefile would spell out how to produce
-@code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
+another. For example the makefile would spell out how to produce
+@file{ballad.pdf} and @file{ballad.midi} from @file{ballad.ly} by
running Lilypond.
There are times when it is a good idea to create a @code{Makefile}
different output options (e.g. full score, parts, conductor's
score, piano reduction, etc.), or for projects that
require difficult commands to build them (such as
-@code{lilypond-book} projects). Makefiles vary greatly in
+@code{lilypond-book} projects). Makefiles vary greatly in
complexity and flexibility, according to the needs and skills of
-the authors. The program GNU Make comes installed on GNU/Linux
+the authors. The program GNU Make comes installed on GNU/Linux
distributions and on MacOS X, and it is also available for Windows.
See the @strong{GNU Make Manual} for full details on using
can do.
The commands to define rules in a makefile differ
-according to platform; for instance the various forms of Linux and
-MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
+according to platform; for instance the various forms of GNU/Linux and
+MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
MacOS X, you need to configure the system to use the command-line
-intepreter. Here are some example makefiles, with versions for both
-Linux/MacOS and Windows.
+interpreter. Here are some example makefiles, with versions for both
+GNU/Linux/MacOS and Windows.
The first example is for an orchestral work in four
movements with a directory structure as follows:
`-- symphonyDefs.ily
@end example
-The @code{.ly} files in the @code{Scores} and
-@code{Parts} directories get their notes from @code{.ily}
-files in the @code{Notes} directory:
+The @file{.ly} files in the @file{Scores} and
+@file{Parts} directories get their notes from @file{.ily}
+files in the @file{Notes} directory:
@example
%%% top of file "symphony-cello.ly"
-\include ../definitions.ily
+\include ../symphonyDefs.ily
\include ../Notes/cello.ily
@end example
The makefile will have targets of @code{score} (entire piece in
full score), @code{movements} (individual movements in full score),
-and @code{parts} (individual parts for performers). There
+and @code{parts} (individual parts for performers). There
is also a target @code{archive} that will create a tarball of
-the source files, suitable for sharing via web or email. Here is
-the makefile for GNU/Linux or MacOS X. It should be saved with the
+the source files, suitable for sharing via web or email. Here is
+the makefile for GNU/Linux or MacOS X. It should be saved with the
name @code{Makefile} in the top directory of the project:
@warning{When a target or pattern rule is defined, the
@end example
-There are special complications on the Windows platform. After
+There are special complications on the Windows platform. After
downloading and installing GNU Make for Windows, you must set the
correct path in the system's environment variables so that the
-DOS shell can find the Make program. To do this, right-click on
+DOS shell can find the Make program. To do this, right-click on
"My Computer," then choose @code{Properties} and
-@code{Advanced}. Click @code{Environment Variables}, and then
+@code{Advanced}. Click @code{Environment Variables}, and then
in the @code{System Variables} pane, highlight @code{Path}, click
@code{edit}, and add the path to the GNU Make executable file, which
will look something like this:
The makefile itself has to be altered to handle different shell
commands and to deal with spaces that are present
-in some default system directories. The @code{archive} target
+in some default system directories. The @code{archive} target
is eliminated since Windows does not have the @code{tar} command,
and Windows also has a different default extension for midi files.
The next Makefile is for a @command{lilypond-book} document done in
-LaTeX. This project has an index, which requires that the
-@command{latex} command be run twice to update links. Output files are
+LaTeX. This project has an index, which requires that the
+@command{latex} command be run twice to update links. Output files are
all stored in the @code{out} directory for .pdf output and in the
@code{htmlout} directory for the html output.
TODO: make this thing work on Windows
-The previous makefile does not work on Windows. An alternative
+The previous makefile does not work on Windows. An alternative
for Windows users would be to create a simple batch file
-containing the build commands. This will not
+containing the build commands. This will not
keep track of dependencies the way a makefile does, but it at
-least reduces the build process to a single command. Save the
+least reduces the build process to a single command. Save the
following code as @command{build.bat} or @command{build.cmd}.
The batch file can be run at the DOS prompt or by simply
double-clicking its icon.
projects / lilypond.git / blobdiff