Doc-it: fix the wrong committishes (bad object) in .texidoc files

[lilypond.git] / Documentation / usage / suggestions.itely

@c -*- coding: utf-8; mode: texinfo; -*-

@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.14.0"

@node Suggestions for writing files
@chapter Suggestions for writing files

Now you're ready to begin writing larger LilyPond input files --
not just the little examples in the tutorial, but whole pieces.
But how should you go about doing it?

As long as LilyPond can understand your input files and produce
the output that you want, it doesn't matter what your input files
look like.  However, there are a few other things to consider when
writing LilyPond input files.

@itemize
@item What if you make a mistake?  The structure of a LilyPond
file can make certain errors easier (or harder) to find.

@item What if you want to share your input files with somebody
else?  In fact, what if you want to alter your own input files in
a few years?  Some LilyPond input files are understandable at
first glance; others may leave you scratching your head
for an hour.

@item What if you want to upgrade your LilyPond file for use
with a later version of LilyPond?  The input syntax changes
occasionally as LilyPond improves.  Most changes can be
done automatically with @code{convert-ly}, but some changes
might require manual assistance.  LilyPond input files can be
structured in order to be easier (or harder) to update.

@end itemize

@menu
* General suggestions::
* Typesetting existing music::
* Large projects::
* Troubleshooting::
* Make and Makefiles::
@end menu


@node General suggestions
@section General suggestions

Here are a few suggestions that can help you to avoid or fix
problems:

@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
@rlearning{Saving typing with variables and functions}, and
@rlearning{Style sheets}.

@end itemize


@node Typesetting existing music
@section Typesetting existing music

If you are entering music from an existing score (i.e., typesetting a
piece of existing sheet music),

@itemize

@item Enter the manuscript (the physical copy of the music) into
LilyPond one system at a time (but still only one bar per line of text),
and check each system when you finish it.  You may use the
@code{showLastLength} or @code{showFirstLength} properties to speed up
processing -- see @ruser{Skipping corrected music}.

@item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
in the input file whenever the manuscript has a line break.  This
makes it much easier to compare the LilyPond music to the original
music.  When you are finished proofreading your score, you may
define @code{mBreak = @{ @}} to remove all those line breaks.  This
will allow LilyPond to place line breaks wherever it feels are
best.

@item When entering a part for a transposing instrument into a
variable, it is recommended that the notes are wrapped in

@example
\transpose c natural-pitch @{...@}
@end example

@noindent
(where @code{natural-pitch} is the open pitch of the instrument) so
that the music in the variable is effectively in C. You can transpose
it back again when the variable is used, if required, but you might
not want to (e.g., when printing a score in concert pitch,
converting a trombone part from treble to bass clef, etc.)
Mistakes in transpositions are less likely if all the music in
variables is at a consistent pitch.

Also, only ever transpose to/from C. That means that the only other
keys you will use are the natural pitches of the instruments - bes
for a B-flat trumpet, aes for an A-flat clarinet, etc.

@end itemize


@node Large projects
@section Large projects

When working on a large project, having a clear structure to your
lilypond input files becomes vital.

@itemize

@item @strong{Use a variable for each voice}, with a minimum of
structure inside the definition.  The structure of the
@code{\score} section is the most likely thing to change;
the @code{violin} definition is extremely unlikely to change
in a new version of LilyPond.

@example
violin = \relative c'' @{
g4 c'8. e16
@}
...
\score @{
  \new GrandStaff @{
    \new Staff @{
      \violin
    @}
  @}
@}
@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}.

@example
fthenp = _\markup@{
  \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
violin = \relative c'' @{
g4\fthenp c'8. e16
@}
@end example

@end itemize


@node Troubleshooting
@section Troubleshooting

Sooner or later, you will write a file that LilyPond cannot
compile.  The messages that LilyPond gives may help
you find the error, but in many cases you need to do some
investigation to determine the source of the problem.

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
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
must exist in the portion you just commented.  If it doesn't
work, then keep on commenting out material until you have
something that works.

In an extreme case, you might end up with only

@example
\score @{
  <<
    % \melody
    % \harmony
    % \bass
  >>
  \layout@{@}
@}
@end example

@noindent
(in other words, a file without any music)

If that happens, don't give up.  Uncomment a bit -- say,
the bass part -- and see if it works.  If it doesn't work,
then comment out all of the bass music (but leave
@code{\bass} in the @code{\score} uncommented.

@example
bass = \relative c' @{
%@{
  c4 c c c
  d d d d
%@}
@}
@end example

Now start slowly uncommenting more and more of the
@code{bass} part until you find the problem line.

Another very useful debugging technique is constructing
@rweb{Tiny examples}.


@node Make and Makefiles
@section Make and Makefiles

@cindex makefiles
@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
@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
@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}
for your project, either for your own convenience or
as a courtesy to others who might have access to your source files.
This is true for very large projects with many included files and
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
complexity and flexibility, according to the needs and skills of
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
@code{make}, as what follows here gives only a glimpse of what it
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
MacOS X, you need to configure the system to use the command-line
interpreter.  Here are some example makefiles, with versions for both
Linux/MacOS and Windows.

The first example is for an orchestral work in four
movements with a directory structure as follows:

@example
Symphony/
|-- MIDI/
|-- Makefile
|-- Notes/
|   |-- cello.ily
|   |-- figures.ily
|   |-- horn.ily
|   |-- oboe.ily
|   |-- trioString.ily
|   |-- viola.ily
|   |-- violinOne.ily
|   `-- violinTwo.ily
|-- PDF/
|-- Parts/
|   |-- symphony-cello.ly
|   |-- symphony-horn.ly
|   |-- symphony-oboes.ly
|   |-- symphony-viola.ly
|   |-- symphony-violinOne.ly
|   `-- symphony-violinTwo.ly
|-- Scores/
|   |-- symphony.ly
|   |-- symphonyI.ly
|   |-- symphonyII.ly
|   |-- symphonyIII.ly
|   `-- symphonyIV.ly
`-- symphonyDefs.ily
@end example

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 ../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
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
name @code{Makefile} in the top directory of the project:

@warning{When a target or pattern rule is defined, the
subsequent lines must begin with tabs, not spaces.}

@example
# the name stem of the output files
piece = symphony
# determine how many processors are present
CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
# The command to run lilypond
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click -djob-count=$(CPU_CORES)

# The suffixes used in this Makefile.
.SUFFIXES: .ly .ily .pdf .midi

# Input and output files are searched in the directories listed in
# the VPATH variable.  All of them are subdirectories of the current
# directory (given by the GNU make variable `CURDIR').
VPATH = \
  $(CURDIR)/Scores \
  $(CURDIR)/PDF \
  $(CURDIR)/Parts \
  $(CURDIR)/Notes

# The pattern rule to create PDF and MIDI files from a LY input file.
# The .pdf output files are put into the `PDF' subdirectory, and the
# .midi files go into the `MIDI' subdirectory.
%.pdf %.midi: %.ly
        $(LILY_CMD) $<; \           # this line begins with a tab
        if test -f "$*.pdf"; then \
            mv "$*.pdf" PDF/; \
        fi; \
        if test -f "$*.midi"; then \
            mv "$*.midi" MIDI/; \
        fi

notes = \
  cello.ily \
  horn.ily \
  oboe.ily \
  viola.ily \
  violinOne.ily \
  violinTwo.ily

# The dependencies of the movements.
$(piece)I.pdf: $(piece)I.ly $(notes)
$(piece)II.pdf: $(piece)II.ly $(notes)
$(piece)III.pdf: $(piece)III.ly $(notes)
$(piece)IV.pdf: $(piece)IV.ly $(notes)

# The dependencies of the full score.
$(piece).pdf: $(piece).ly $(notes)

# The dependencies of the parts.
$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily

# Type `make score' to generate the full score of all four
# movements as one file.
.PHONY: score
score: $(piece).pdf

# Type `make parts' to generate all parts.
# Type `make foo.pdf' to generate the part for instrument `foo'.
# Example: `make symphony-cello.pdf'.
.PHONY: parts
parts: $(piece)-cello.pdf \
       $(piece)-violinOne.pdf \
       $(piece)-violinTwo.pdf \
       $(piece)-viola.pdf \
       $(piece)-oboes.pdf \
       $(piece)-horn.pdf

# Type `make movements' to generate files for the
# four movements separately.
.PHONY: movements
movements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parts movements

archive:
        tar -cvvf stamitz.tar \       # this line begins with a tab
        --exclude=*pdf --exclude=*~ \
        --exclude=*midi --exclude=*.tar \
        ../Stamitz/*
@end example


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
"My Computer," then choose @code{Properties} and
@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:

@example
C:\Program Files\GnuWin32\bin
@end example

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
is eliminated since Windows does not have the @code{tar} command,
and Windows also has a different default extension for midi files.


@example
## WINDOWS VERSION
##
piece = symphony
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click \
                    -djob-count=$(NUMBER_OF_PROCESSORS)

#get the 8.3 name of CURDIR (workaround for spaces in PATH)
workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
          do @@echo %%~sb)

.SUFFIXES: .ly .ily .pdf .mid

VPATH = \
  $(workdir)/Scores \
  $(workdir)/PDF \
  $(workdir)/Parts \
  $(workdir)/Notes

%.pdf %.mid: %.ly
        $(LILY_CMD) $<      # this line begins with a tab
        if exist "$*.pdf"  move /Y "$*.pdf"  PDF/ # begin with tab
        if exist "$*.mid" move /Y "$*.mid" MIDI/  # begin with tab

notes = \
  cello.ily \
  figures.ily \
  horn.ily \
  oboe.ily \
  trioString.ily \
  viola.ily \
  violinOne.ily \
  violinTwo.ily

$(piece)I.pdf: $(piece)I.ly $(notes)
$(piece)II.pdf: $(piece)II.ly $(notes)
$(piece)III.pdf: $(piece)III.ly $(notes)
$(piece)IV.pdf: $(piece)IV.ly $(notes)

$(piece).pdf: $(piece).ly $(notes)

$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily

.PHONY: score
score: $(piece).pdf

.PHONY: parts
parts: $(piece)-cello.pdf \
       $(piece)-violinOne.pdf \
       $(piece)-violinTwo.pdf \
       $(piece)-viola.pdf \
       $(piece)-oboes.pdf \
       $(piece)-horn.pdf

.PHONY: movements
movements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parts movements
@end example


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
all stored in the @code{out} directory for .pdf output and in the
@code{htmlout} directory for the html output.

@example
SHELL=/bin/sh
FILE=myproject
OUTDIR=out
WEBDIR=htmlout
VIEWER=acroread
BROWSER=firefox
LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
PDF=cd $(OUTDIR) && pdflatex $(FILE)
HTML=cd $(WEBDIR) && latex2html $(FILE)
INDEX=cd $(OUTDIR) && makeindex $(FILE)
PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &

all: pdf web keep

pdf:
        $(LILYBOOK_PDF)  # begin with tab
        $(PDF)           # begin with tab
        $(INDEX)         # begin with tab
        $(PDF)           # begin with tab
        $(PREVIEW)       # begin with tab

web:
        $(LILYBOOK_HTML) # begin with tab
        $(HTML)          # begin with tab
        cp -R $(WEBDIR)/$(FILE)/ ./  # begin with tab
        $(BROWSER) $(FILE)/$(FILE).html &  # begin with tab

keep: pdf
        cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf  # begin with tab

clean:
        rm -rf $(OUTDIR) # begin with tab

web-clean:
        rm -rf $(WEBDIR) # begin with tab

archive:
        tar -cvvf myproject.tar \ # begin this line with tab
        --exclude=out/* \
        --exclude=htmlout/* \
        --exclude=myproject/* \
        --exclude=*midi \
        --exclude=*pdf \
        --exclude=*~ \
        ../MyProject/*
@end example

TODO: make this thing work on Windows

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
keep track of dependencies the way a makefile does, but it at
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.

@example
lilypond-book --output=out --pdf myproject.lytex
cd out
pdflatex myproject
makeindex myproject
pdflatex myproject
cd ..
copy out\myproject.pdf MyProject.pdf
@end example


@seealso

This manual:
@ref{Command-line usage},
@ref{lilypond-book}