This chapter gives a basic introduction to working with LilyPond.
@menu
-* Compiling a file::
-* How to write input files::
-* How to read the manuals::
+* Compiling a file::
+* How to write input files::
+* How to read the manuals::
@end menu
@node Compiling a file
@section Compiling a file
-FIXME: insert text
+This section introduces @qq{compiling}---the processing of
+LilyPond input files (written by you) to produce output files.
@menu
-* Entering input::
-* MacOS X::
-* Windows::
-* Command-line::
+* Entering input::
+* MacOS X::
+* Windows::
+* Command-line::
@end menu
@node Entering input
@cindex example, first
@cindex case sensitive
-@qq{Compiling} is the term used for processing an input file
-in LilyPond format to produce a file which can be printed and
-(optionally) a MIDI file which can be played. LilyPond input
-files are simple text files. The first example
-shows what a simple input file looks like.
+@qq{Compiling} is the term used for processing an input file in
+LilyPond format to produce output file(s). Output files are
+generally PDF (for printing or viewing), MIDI (for playing), and
+PNG (for online use). LilyPond input files are simple text files.
-To create sheet music, we write an input file that specifies the
-notation. For example, if we write:
+This example shows a simple input file:
@example
+\version "@w{@version{}}"
@{
c' e' g' e'
@}
@end example
-@noindent
-the result looks like this:
+The graphical output is:
@c in this case we don't want verbatim
@lilypond[quote]
@warning{Notes and lyrics in LilyPond input must always be
surrounded by @w{@strong{@{ curly braces @}}}. The braces
should also be surrounded by a space unless they are at the
-beginning or end of a line to avoid ambiguities. The braces may
+beginning or end of a line to avoid ambiguities. They may
be omitted in some examples in this manual, but don't forget them
in your own music! For more information about the display of
examples in the manual, see @ref{How to read the manuals}.}
@smallspace
-@subheading Viewing output
+@subheading Producing output
-@c TODO: move index entries
@cindex PDF file
@cindex viewing music
@cindex text editors
-@cindex running LilyPond under MacOS X
-@cindex MacOS X, running LilyPond
-@cindex running LilyPond under Windows
-@cindex Windows, running LilyPond
-@cindex running LilyPond under Unix
-@cindex Unix, running LilyPond
-Producing output depends on your operating system and the
-program(s) you use.
+The method of producing output depends on your operating system
+and the program(s) you use.
@itemize
@end itemize
-There are several other text editors available with better support
-for LilyPond. For more information, see
+There are several other text editors available with specific
+support for LilyPond. For more information, see
@rweb{Alternate input}.
@warning{The first time you ever run LilyPond, it may take a
minute or two because all of the system fonts have to be analyzed
first. After this, LilyPond will be much faster!}
+@cindex running LilyPond under MacOS X
+@cindex MacOS X, running LilyPond
@node MacOS X
@subsection MacOS X
-@warning{These instructions assume that you are using the built-in
-LilyPad editor. If you are using any of the programs described in
+@warning{These instructions assume that you are using the LilyPond
+application. If you are using any of the programs described in
@rweb{Alternate input}, please consult the documentation for
-those programs if you have any problems compiling a file.}
+those programs if you have any problems.}
+
+
+@subsubheading Step 1. Create your @file{.ly} file
+
+Double click the @command{LilyPond.app}, an example file will open.
+
+@sourceimage{Learning_Macos_welcome,,,}
+
+From the menus along the top left of your screen, select
+@w{@code{File > Save}}.
+
+@sourceimage{Learning_Macos_Save_menu,,,}
+
+Choose a name for your file, for example @file{test.ly}.
+
+@sourceimage{Learning_Macos_Save_file_with_name,,,}
+
+@subsubheading Step 2. Compile (with LilyPad)
-If you double click @command{LilyPond.app}, it will open with an
-example file. Save it, for example, to @file{test.ly} on your
-Desktop, and then process it with the menu command
-@w{@code{Compile > Typeset File}}. The resulting PDF file will be
-displayed on your screen.
+From the same menus, select
+@w{@code{Compile > Tyepset}}.
-For future use of LilyPond, you should begin by selecting @q{New}
-or @q{Open}. You must save your file before typesetting it. If
-any errors occur in processing, please see the log window.
+@sourceimage{Learning_Macos_Typeset_menu,,,}
-@c FIXME: add screenshots
+A new window will open showing a progress log of the compilation
+of the file you have just saved.
+
+@sourceimage{Learning_Macos_Compiling_log,,,}
+
+
+@subsubheading Step 3. View output
+
+Once the compilation has finished, a PDF file will be created with
+the same name as the original file and will be automatically
+opened in the default PDF viewer and displayed on your screen.
+
+@sourceimage{Learning_Macos_pdf_output,,,}
+
+
+@subsubheading Other commands
+
+To create new files for LilyPond, begin by selecting
+@w{@code{File > New}}
+
+@sourceimage{Learning_Macos_New_menu,,,}
+
+or @w{@code{File > Open}} to open and edit existing files you have
+saved previously.
+
+@sourceimage{Learning_Macos_Open_menu,,,}
+
+You must save any new edits you make to your file before you
+@w{@code{Compile > Tyepset}} and if the PDF file is not displayed
+check the window with the progress log for any errors.
+
+If you are not using the defualt Preview PDF viewer that comes
+with the Mac Operating system and you have the PDF file generated
+from a previous compilation open, then any further compilations
+may fail to generate an update PDF until you close the original.
+
+@cindex running LilyPond under Windows
+@cindex Windows, running LilyPond
@node Windows
@subsection Windows
@rweb{Alternate input}, please consult the documentation for
those programs if you have any problems compiling a file.}
-On Windows, if you double-click in the LilyPond icon on the
-Desktop, it will open a simple text editor with an example file.
-Save it, for example, to @file{test.ly} on your Desktop and then
-double-click on the file to process it (the file icon looks like a
-note). After some seconds, you will get a file @file{test.pdf} on
-your desktop. Double-click on this PDF file to view the typeset
-score. An alternative method to process the @file{test.ly} file
-is to drag and drop it onto the LilyPond icon using your mouse
-pointer.
-To edit an existing @file{.ly} file, right-click on it and
-select @qq{Edit source}. To get an empty file to start from, run
-the editor as described above and use @qq{New} in
-the @qq{File} menu, or right-click on the desktop and select
-@qq{New..Text Document}, change its name to a name of your choice
-and change the file extension to @code{.ly}. Double-click the
-icon to type in your LilyPond source code as before.
+@subsubheading Step 1. Create your @file{.ly} file
+
+Double-click the @command{LilyPond.app}, an example file will open.
+
+@sourceimage{Learning_Win7_Welcome_File_Whole,,,}
+
+From the menus that appear alonbg the top of the example file,
+select @w{@code{File > Save as}}. Do not use the @w{@code{File > Save}}
+for the example file as this will not work until you have given it a
+valid Lilypong file name.
+
+@sourceimage{Learning_Win7_Save_Menu,,,}
+
+Choose a name for your file, for example @file{test.ly}.
-Double-clicking the file does not only result in a PDF file, but
-also produces a @file{.log} file that contains some information on
-what LilyPond has done to the file. If any errors occur, please
-examine this file.
+@sourceimage{Learning_Win7_Save_File_With_Name,,,}
-@c FIXME: add screenshots
+@subsubheading Step 2a. Compile (with drag-and-drop)
+
+Depending on what you prefer, to compile your file either:
+
+Drag-and-drop the file directly onto the LilyPond icon.
+
+@sourceimage{Learning_Win7_Open_Dragndrop,,,}
+
+Right-click on the file and from the pop-up context menu choose
+@w{@code{Open with > LilyPond}}.
+
+@sourceimage{Learning_Win7_Open_Context_Menu,,,}
+
+
+@subsubheading Step 2b. Compile (with double-clicking)
+
+Or simply double-click the @file{test.ly}.
+
+
+@subsubheading Step 3. View output
+
+During the compilation of the @file{test.ly} file, a command window
+will, very briefly open and then close. Three additional files will
+have been created during this process.
+
+@sourceimage{Learning_Win7_All_Files_Created,,,}
+
+The PDF file contains the engraved @file{test.ly} file.
+
+@sourceimage{Learning_Win7_Pdf_Output,,,}
+
+
+@subsubheading Other commands
+
+To create a new file, begin by selecting @w{@code{File > New}} from
+within any previously created file.
+
+@sourceimage{Learning_Win7_New_Menu,,,}
+
+@noindent
+or @w{@code{File > Open}} to open and edit any files you have saved
+before.
+
+@sourceimage{Learning_Win7_Open_Menu,,,}
+
+You must save any new edits you make before you compile it and if the
+PDF file is not created, check the log file that will have been created
+during the compilation attempt, for any errors.
+
+@sourceimage{Learning_Win7_Log_File,,,}
+
+This log file is overwritten each time you compile your LilyPond file.
+
+The PS file is used internally by LilyPond to create the PDF file and
+can be ignored. It also gets overwritten each time you compile your
+file.
+
+If you are viewing your file in a PDF viewer, then you must close the
+PDF if you wish to make a new compilation as it may fail to create
+the new PDF while it is still being viewed.
+
+@cindex running LilyPond under Unix
+@cindex Unix, running LilyPond
@node Command-line
@subsection Command-line
-@warning{These instructions assume that you are using commond unix
+@warning{These instructions assume that you are familiar with
command-line programs. If you are using any of the programs
described in @rweb{Alternate input}, please consult the
documentation for those programs if you have any problems
compiling a file.}
+@subsubheading Step 1. Create your @file{.ly} file
+
Create a text file called @file{test.ly} and enter:
@example
+\version "@w{@version{}}"
@{
c' e' g' e'
@}
@end example
-To process @file{test.ly}, proceed as follows:
+
+@subsubheading Step 2. Compile (with command-line)
+
+To process @file{test.ly}, type the following at the command prompt:
@example
lilypond test.ly
You will see something resembling:
@example
-lilypond test.ly
GNU LilyPond @version{}
Processing `test.ly'
Parsing...
Interpreting music...
Preprocessing graphical objects...
-Finding the ideal number of pages...
-Fitting music on 1 page...
+Solving 1 page-breaking chunks...[1: 1 pages]
Drawing systems...
Layout output to `test.ps'...
-Converting to `test.pdf'...
+Converting to `./test.pdf'...
@end example
+@subsubheading Step 3. View output
+
You may view or print the resulting @file{text.pdf}.
@node How to write input files
@section How to write input files
-FIXME: insert text
+This section introduces some basic LilyPond syntax to help get you
+started writing input files.
@menu
-* Simple notation::
-* Working on input files::
+* Simple notation::
+* Working on input files::
@end menu
@cindex case sensitive
@cindex whitespace insensitive
@cindex expressions
+@cindex versioning
+@cindex version
+@cindex version number
+@funindex \version
@funindex { ... }
@funindex %
@funindex %@{ ... %@}
LilyPond input files are similar to source files in many common
-programming languages. They are case sensitive, and white-space
+programming languages. They contain a version statement,
+are case sensitive, and white-space
is generally ignored. Expressions are formed with curly braces
@{ @}, and comments are denoted with @code{%} or
@w{@code{%@{ ... %@}}}.
@itemize
+@item
+@strong{Version statement}:
+Every LilyPond file should contain a version statement. A version
+statement is a line that describes the version of LilyPond for which
+the file was written, as in the following example:
+
+@example
+\version "@w{@version{}}"
+@end example
+
+By convention, the version statement is placed at the top of the
+LilyPond file.
+
+The version statement is important for at least two reasons. First,
+it allows automatic updating of the input file as LilyPond syntax
+changes. Second, it describes the version of LilyPond needed to
+compile the file.
+
+If the version statement is omitted from an input file, LilyPond will print
+a warning during the compilation of the file.
+
@item
@strong{Case sensitive}:
it matters whether you enter a letter in lower case (e.g.
@node How to read the manuals
@section How to read the manuals
-FIXME: fluff here
+This section shows how to read the documentation efficiently, and
+also introduces some useful interactive features available in the
+online version.
@menu
-* Omitting braces::
-* Clickable examples::
-* Keyboard navigation::
-* Overview of manuals::
+* Omitted material::
+* Clickable examples::
+* Keyboard navigation::
+* Overview of manuals::
@end menu
-@node Omitting braces
-@subsection Omitting braces
+@node Omitted material
+@subsection Omitted material
@cindex how to read the manual
own. Most people want to add material to an existing piece, so we
format the manual this way.
+Also, remember that every LilyPond file should have a @code{@bs{}version}
+statement. Because the examples in the manuals are snippets, not files,
+the @code{@bs{}version} statement is omitted. But you should make a
+practice of including them in your files.
@node Clickable examples
@subsection Clickable examples
projects / lilypond.git / blobdiff