@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of web/download.itexi and
@c learning/tutorial.itely

@c This is about "compiling" a lilypond file
@c (Learning 1 Tutorial), **not** compiling the
@c source code.

@macro lilypadOSX
@warning{These instructions assume that you are using the LilyPond
application.  If you are using any of the programs described in
@rweb{Easier editing}, please consult the documentation for
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)

From the same menus, select
@w{@code{Compile > Typeset}}.

@sourceimage{Learning_Macos_Typeset_menu,,,}

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 > Typeset}} and if the PDF file is not displayed
check the window with the progress log for any errors.

If you are not using the default 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.



@end macro


@macro lilypadWindows
@warning{These instructions assume that you are using the built-in
LilyPad editor.  If you are using any of the programs described in
@rweb{Easier editing}, please consult the documentation for
those programs if you have any problems compiling a file.}


@subsubheading Step 1. Create your @file{.ly} file

Double-click the LilyPond icon on your desktop, an example file will open.

@sourceimage{Learning_Win7_Welcome_File_Whole,,,}

From the menus that appear along 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 LilyPond file name.

@sourceimage{Learning_Win7_Save_Menu,,,}

Choose a name for your file, for example @file{test.ly}.

@sourceimage{Learning_Win7_Save_File_With_Name,,,}


@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.


@end macro


@c not lilypad at all, but I ran out of names.  :(
@macro lilypadCommandLine
@warning{These instructions assume that you are familiar with
command-line programs.  If you are using any of the programs
described in @rweb{Easier editing}, 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:

@c double \\ required because this is inside a macro!
@example
\\version "@w{@versionStable{}}"
@{
  c' e' g' e'
@}
@end example


@subsubheading Step 2. Compile (with command-line)

To process @file{test.ly}, type the following at the command prompt:

@example
lilypond test.ly
@end example

@noindent
You will see something resembling:

@example
GNU LilyPond @w{@versionStable{}}
Processing `test.ly'
Parsing...
Interpreting music...
Preprocessing graphical objects...
Solving 1 page-breaking chunks...[1: 1 pages]
Drawing systems...
Layout output to `test.ps'...
Converting to `./test.pdf'...
Success: compilation successfully completed
@end example

@subsubheading Step 3. View output

You may view or print the resulting @file{test.pdf}.

@end macro