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 > Tyepset}}.
  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 > Tyepset}} 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, an example file will open.
  90
  91 @sourceimage{Learning_Win7_Welcome_File_Whole,,,}
  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{Learning_Win7_Save_Menu,,,}
  99
 100 Choose a name for your file, for example @file{test.ly}.
 101
 102 @sourceimage{Learning_Win7_Save_File_With_Name,,,}
 103
 104
 105 @subsubheading Step 2a. Compile (with drag-and-drop)
 106
 107 Depending on what you prefer, to compile your file either:
 108
 109 Drag-and-drop the file directly onto the LilyPond icon.
 110
 111 @sourceimage{Learning_Win7_Open_Dragndrop,,,}
 112
 113 @c FIXME: use 2nd-click? Right/Left depends on where you place your mouse.
 114 Right-click on the file and from the pop-up context menu choose
 115 @w{@code{Open with > LilyPond}}.
 116
 117 @sourceimage{Learning_Win7_Open_Context_Menu,,,}
 118
 119
 120 @c FIXME: why present/advise the best/simplest for last?
 121 @subsubheading Step 2b. Compile (with double-clicking)
 122
 123 Or simply double-click the @file{test.ly}.
 124
 125
 126 @subsubheading Step 3. View output
 127
 128 During the compilation of the @file{test.ly} file, a command window
 129 will, very briefly open and then close. Three additional files will
 130 have been created during this process.
 131
 132 @sourceimage{Learning_Win7_All_Files_Created,,,}
 133
 134 The PDF file contains the engraved @file{test.ly} file.
 135
 136 @sourceimage{Learning_Win7_Pdf_Output,,,}
 137
 138
 139 @subsubheading Other commands
 140
 141 To create a new file, begin by selecting @w{@code{File > New}} from
 142 within any previously created file.
 143
 144 @sourceimage{Learning_Win7_New_Menu,,,}
 145
 146 @noindent
 147 or @w{@code{File > Open}} to open and edit any files you have saved
 148 before.
 149
 150 @sourceimage{Learning_Win7_Open_Menu,,,}
 151
 152 You must save any new edits you make before you compile it and if the
 153 PDF file is not created, check the log file that will have been created
 154 during the compilation attempt, for any errors.
 155
 156 @sourceimage{Learning_Win7_Log_File,,,}
 157
 158 This log file is overwritten each time you compile your LilyPond file.
 159
 160 The PS file is used internally by LilyPond to create the PDF file and
 161 can be ignored. It also gets overwritten each time you compile your
 162 file.
 163
 164 If you are viewing your file in a PDF viewer, then you must close the
 165 PDF if you wish to make a new compilation as it may fail to create
 166 the new PDF while it is still being viewed.
 167
 168
 169 @end macro
 170
 171
 172 @c not lilypad at all, but I ran out of names.  :(
 173 @macro lilypadCommandLine
 174 @warning{These instructions assume that you are familiar with
 175 command-line programs.  If you are using any of the programs
 176 described in @rweb{Easier editing}, please consult the
 177 documentation for those programs if you have any problems
 178 compiling a file.}
 179
 180
 181 @subsubheading Step 1. Create your @file{.ly} file
 182
 183 Create a text file called @file{test.ly} and enter:
 184
 185 @c double \\ required because this is inside a macro!
 186 @example
 187 \\version "@w{@version{}}"
 188 @{
 189   c' e' g' e'
 190 @}
 191 @end example
 192
 193
 194 @subsubheading Step 2. Compile (with command-line)
 195
 196 To process @file{test.ly}, type the following at the command prompt:
 197
 198 @example
 199 lilypond test.ly
 200 @end example
 201
 202 @noindent
 203 You will see something resembling:
 204
 205 @example
 206 GNU LilyPond @w{@version{}}
 207 Processing `test.ly'
 208 Parsing...
 209 Interpreting music...
 210 Preprocessing graphical objects...
 211 Solving 1 page-breaking chunks...[1: 1 pages]
 212 Drawing systems...
 213 Layout output to `test.ps'...
 214 Converting to `./test.pdf'...
 215 @end example
 216
 217 @subsubheading Step 3. View output
 218
 219 You may view or print the resulting @file{test.pdf}.
 220
 221 @end macro
 222
 223