Documentation/included/generating-output.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @c This file is part of web/download.itexi and
   3 @c learning/tutorial.itely
   4
   5 @c This is about "compiling" a lilypond file
   6 @c (Learning 1 Tutorial), **not** compiling the
   7 @c source code.
   8
   9 @macro lilypadOSX
  10 @warning{These instructions assume that you are using the LilyPond
  11 application.  If you are using any of the programs described in
  12 @rweb{Easier editing}, please consult the documentation for
  13 those programs if you have any problems.}
  14
  15
  16 @subsubheading Step 1. Create your @file{.ly} file
  17
  18 Double click the @command{LilyPond.app}, an example file will open.
  19
  20 @sourceimage{Learning_Macos_welcome,,,}
  21
  22 From the menus along the top left of your screen, select
  23 @w{@code{File > Save}}.
  24
  25 @sourceimage{Learning_Macos_Save_menu,,,}
  26
  27 Choose a name for your file, for example @file{test.ly}.
  28
  29 @sourceimage{Learning_Macos_Save_file_with_name,,,}
  30
  31
  32 @subsubheading Step 2. Compile (with LilyPad)
  33
  34 From the same menus, select
  35 @w{@code{Compile > Typeset}}.
  36
  37 @sourceimage{Learning_Macos_Typeset_menu,,,}
  38
  39 A new window will open showing a progress log of the compilation
  40 of the file you have just saved.
  41
  42 @sourceimage{Learning_Macos_Compiling_log,,,}
  43
  44
  45 @subsubheading Step 3. View output
  46
  47 Once the compilation has finished, a PDF file will be created with
  48 the same name as the original file and will be automatically
  49 opened in the default PDF viewer and displayed on your screen.
  50
  51 @sourceimage{Learning_Macos_pdf_output,,,}
  52
  53
  54 @subsubheading Other commands
  55
  56 To create new files for LilyPond, begin by selecting
  57 @w{@code{File > New}}
  58
  59 @sourceimage{Learning_Macos_New_menu,,,}
  60
  61 or @w{@code{File > Open}} to open and edit existing files you have
  62 saved previously.
  63
  64 @sourceimage{Learning_Macos_Open_menu,,,}
  65
  66 You must save any new edits you make to your file before you
  67 @w{@code{Compile > Typeset}} and if the PDF file is not displayed
  68 check the window with the progress log for any errors.
  69
  70 If you are not using the default Preview PDF viewer that comes
  71 with the Mac Operating system and you have the PDF file generated
  72 from a previous compilation open, then any further compilations
  73 may fail to generate an update PDF until you close the original.
  74
  75
  76
  77 @end macro
  78
  79
  80 @macro lilypadWindows
  81 @warning{These instructions assume that you are using the built-in
  82 LilyPad editor.  If you are using any of the programs described in
  83 @rweb{Easier editing}, please consult the documentation for
  84 those programs if you have any problems compiling a file.}
  85
  86
  87 @subsubheading Step 1. Create your @file{.ly} file
  88
  89 Double-click the LilyPond icon on your desktop and an example file will open.
  90
  91 @sourceimage{LilyPad,,,}
  92
  93 From the menus that appear along the top of the example file,
  94 select @w{@code{File > Save as}}.  Do not use the @w{@code{File > Save}}
  95 for the example file as this will not work until you have given it a
  96 valid LilyPond file name.
  97
  98 @sourceimage{FileSave,,,}
  99
 100 Choose a name for your file, for example @file{test.ly}.
 101
 102 @sourceimage{SaveAs,,,}
 103
 104
 105 @subsubheading Step 2. Compile
 106
 107 To turn your LilyPond file into a music score, you need to compile it. This
 108 can be done a number of ways -- using drag and drop, with right-click,
 109 double-clicking or using the command line (a DOS box).  We'll look at the
 110 first three to start with.
 111
 112 1. Drag-and-drop the file directly onto the LilyPond icon on the desktop.
 113
 114 @sourceimage{DragDrop,,,}
 115
 116 Not much will seem to happen, but after a short while, you should
 117 see two new files on your desktop -- @file{test.log} and
 118 @file{test.pdf}.
 119
 120 2. Right-click on the file and from the pop-up context menu and
 121 choose @w{@code{Generate PDF}}.
 122
 123 @sourceimage{GenPDF,,,}
 124
 125 3. Or simply double-click the @file{test.ly}.
 126
 127
 128 @subsubheading Step 3. View output
 129
 130 @file{test.pdf} contains the engraved @file{test.ly}
 131 file. Double-click it and it should open in your PDF viewer:
 132
 133 @sourceimage{PDFRead,,,}
 134
 135
 136 @subsubheading Other commands
 137
 138 To create a new file, begin by selecting @w{@code{File > New}} from
 139 within any previously created file or @w{@code{File > Open}} to open and
 140 edit any files you have saved before.  You can also edit a file by
 141 right-clicking it and selecting @w{@code{Edit source}}.
 142
 143 @sourceimage{EditFile,,,}
 144
 145 You must save any edits you make before you try to compile your
 146 file.  If the PDF file is not created or the output is not what you
 147 expected, check the log file that will have been created during the
 148 compilation attempt for any errors.
 149
 150 @sourceimage{BadLog,,,}
 151
 152 This log file is overwritten each time you compile your LilyPond file.
 153
 154 If you are viewing your file in a PDF viewer, then you must close the PDF
 155 if you wish to try a new compilation as it may fail to create the new PDF
 156 while it is still being viewed.
 157
 158 @sourceimage{BadLog2,,,}
 159
 160 @end macro
 161
 162
 163 @c not lilypad at all, but I ran out of names.  :(
 164 @macro lilypadCommandLine
 165 @warning{These instructions assume that you are familiar with
 166 command-line programs.  If you are using any of the programs
 167 described in @rweb{Easier editing}, please consult the
 168 documentation for those programs if you have any problems
 169 compiling a file.}
 170
 171
 172 @subsubheading Step 1. Create your @file{.ly} file
 173
 174 Create a text file called @file{test.ly} and enter:
 175
 176 @c double \\ required because this is inside a macro!
 177 @example
 178 \\version "@w{@versionStable{}}"
 179 @{
 180 @ @ c' e' g' e'
 181 @}
 182 @end example
 183
 184
 185 @subsubheading Step 2. Compile (with command-line)
 186
 187 To process @file{test.ly}, type the following at the command prompt:
 188
 189 @example
 190 lilypond test.ly
 191 @end example
 192
 193 @noindent
 194 You will see something resembling:
 195
 196 @example
 197 GNU LilyPond @w{@versionStable{}}
 198 Processing `test.ly'
 199 Parsing...
 200 Interpreting music...
 201 Preprocessing graphical objects...
 202 Solving 1 page-breaking chunks...[1: 1 pages]
 203 Drawing systems...
 204 Layout output to `test.ps'...
 205 Converting to `./test.pdf'...
 206 Success: compilation successfully completed
 207 @end example
 208
 209 @subsubheading Step 3. View output
 210
 211 You may view or print the resulting @file{test.pdf}.
 212
 213 @end macro
 214
 215