Documentation/user/setup.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @c This file is part of lilypond-program.tely
   3 @ignore
   4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c \version "2.11.61"
  11
  12 @node Setup
  13 @chapter Setup
  14
  15 This chapter discusses various post-install configuration options for
  16 LilyPond and various other programs.  This chapter may be safely treated
  17 as a reference: only read a section if it applies to you.
  18
  19 @menu
  20 * Setup for specific Operating Systems::
  21 * Text editor support::
  22 * Point and click::
  23 @end menu
  24
  25
  26 @node Setup for specific Operating Systems
  27 @section Setup for specific Operating Systems
  28
  29 This section explains how to perform additional setup for specific
  30 operating systems.
  31
  32 @menu
  33 * Setup for MacOS X::
  34 @end menu
  35
  36 @node Setup for MacOS X
  37 @subsection Setup for MacOS X
  38
  39 @subsubheading Using Python scripts on MacOS 10.3 or 10.4
  40
  41 LilyPond binaries for MacOS X do not provide Python, but Python 2.4 or
  42 newer is required by @command{convert-ly}.  Therefore, if you use MacOS
  43 10.3 or 10.4, you must install a newer Python version from
  44 @uref{http://python.org/download/}, then edit the first line of
  45 @command{convert-ly} and @command{lilypond-book} as follows: if the
  46 Python binary you just installed is in your @var{PATH}, the first line
  47 should be
  48
  49 @example
  50 #!/usr/bin/env python
  51 @end example
  52
  53 @noindent
  54 otherwise it should be
  55
  56 @example
  57 #!@var{/path/to/newly_installed/python}
  58 @end example
  59
  60
  61 @subsubheading MacOS X on the command line
  62
  63 The scripts --- such as @command{lilypond-book}, @command{convert-ly},
  64 @command{abc2ly}, and even @command{lilypond} itself --- are included
  65 inside the @code{.app} file for MacOS@tie{}X.  They can be run from
  66 the command line by invoking them directly, e.g.
  67
  68 @example
  69 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
  70 @end example
  71
  72 @noindent
  73 The same is true of the other scripts in that directory, including
  74 @command{lilypond-book}, @command{convert-ly}, @command{abc2ly}, etc.
  75
  76 Alternatively, you may create scripts which add the path
  77 automatically.  Create a directory to store these scripts,
  78
  79 @example
  80 mkdir -p ~/bin
  81 cd ~/bin
  82 @end example
  83
  84 Create a file called @code{lilypond} which contains
  85
  86 @example
  87 exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
  88 @end example
  89
  90 Create similar files @code{lilypond-book}, @code{convert-ly}, and
  91 any other helper programs you use (@code{abc2ly}, @code{midi2ly},
  92 etc).  Simply replace the @code{bin/lilypond} with
  93 @code{bin/convert-ly} (or other program name) in the above file.
  94
  95 Make the file executable,
  96
  97 @example
  98 chmod u+x lilypond
  99 @end example
 100
 101 Now, add this directory to your path.  Modify (or create)
 102 a file called @code{.profile} in your home directory such that it contains
 103
 104 @example
 105 export PATH=$PATH:~/bin
 106 @end example
 107
 108 @noindent
 109 This file should end with a blank line.
 110
 111 Note that @var{path/to} will generally be @code{/Applications/}.
 112
 113
 114 @node Text editor support
 115 @section Text editor support
 116
 117 @cindex editors
 118 @cindex vim
 119 @cindex emacs
 120 @cindex modes, editor
 121 @cindex syntax coloring
 122 @cindex coloring, syntax
 123
 124 There is support from different text editors for LilyPond.
 125
 126 @menu
 127 * Emacs mode::
 128 * Vim mode::
 129 * jEdit::
 130 * TexShop::
 131 * TextMate::
 132 * LilyKDE::
 133 @end menu
 134
 135 @node Emacs mode
 136 @subsection Emacs mode
 137
 138 Emacs has a @file{lilypond-mode}, which provides keyword
 139 autocompletion, indentation, LilyPond specific parenthesis matching
 140 and syntax coloring, handy compile short-cuts and reading LilyPond
 141 manuals using Info.  If @file{lilypond-mode} is not installed on your
 142 platform, see below.
 143
 144 An Emacs mode for entering music and running LilyPond is contained in
 145 the source archive in the @file{elisp} directory.  Do @command{make
 146 install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
 147 should be placed to @var{load-path}@file{/site-start.d/} or appended
 148 to your @file{~/.emacs} or @file{~/.emacs.el}.
 149
 150 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
 151 your @var{load-path} by appending the following line (as modified) to your
 152 @file{~/.emacs}
 153
 154 @c any reason we do not advise:  (push "~/site-lisp" load-path)
 155 @example
 156 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 157 @end example
 158
 159
 160 @node Vim mode
 161 @subsection Vim mode
 162
 163 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
 164 along with syntax coloring tools.  A Vim mode for entering music and
 165 running LilyPond is contained in the source archive in @code{$VIM}
 166 directory.
 167
 168 The LilyPond file type is detected if the file
 169 @file{~/.vim/filetype.vim} has the following content
 170
 171 @example
 172 if exists("did_load_filetypes")
 173   finish
 174 endif
 175 augroup filetypedetect
 176   au! BufNewFile,BufRead *.ly           setf lilypond
 177 augroup END
 178 @end example
 179
 180 Please include this path by appending the following line to your
 181 @file{~/.vimrc}
 182
 183 @example
 184 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
 185 @end example
 186
 187 @noindent
 188 where $@{LILYPOND_VERSION@} is your LilyPond version.  If LilyPond was not
 189 installed in @file{/usr/local/}, then change this path accordingly.
 190
 191
 192 @node jEdit
 193 @subsection jEdit
 194
 195 Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit}
 196 text editor, LilyPondTool is the most feature-rich text-based tool for
 197 editing LilyPond scores.  Its features include a Document Wizard with
 198 lyrics support to set up documents easier, and embedded PDF viewer with
 199 advanced point-and-click support.  For screenshots, demos and
 200 installation instructions, visit
 201 @uref{http://lilypondtool@/.organum@/.hu}
 202
 203
 204 @node TexShop
 205 @subsection TexShop
 206
 207 The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop}
 208 editor for MacOS@tie{}X can be extended to run LilyPond, lilypond-book and
 209 convert-ly from within the editor, using the extensions available at
 210 @uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}.
 211
 212
 213 @node TextMate
 214 @subsection TextMate
 215
 216 There is a LilyPond bundle for TextMate.  It may be installed by running
 217
 218 @example
 219 mkdir -p /Library/Application\ Support/TextMate/Bundles
 220 cd /Library/Application\ Support/TextMate/Bundles
 221 svn co http://macromates.com/svn/Bundles/trunk/Bundles/Lilypond.tmbundle/
 222 @end example
 223
 224
 225 @node LilyKDE
 226 @subsection LilyKDE
 227
 228 @uref{http://lilykde.googlecode.com/,LilyKDE} is a plugin for KDE's
 229 text editor @uref{http://kate-editor.org/,Kate}.  It has a powerful Score
 230 Wizard to quickly setup a LilyPond document and an embedded PDF viewer.
 231
 232 LilyKDE can use @uref{http://www.volny.cz/smilauer/rumor/,Rumor},
 233 so music can entered by playing on a MIDI keyboard.
 234
 235 Other features are lyric hyphenation and running LilyPond on multiple files
 236 at once from within the KDE file manager.
 237
 238
 239 @node Point and click
 240 @section Point and click
 241 @cindex point and click
 242
 243
 244 Point and click lets you find notes in the input by clicking on them
 245 in the PDF viewer.  This makes it easier to find input that causes
 246 some error in the sheet music.
 247
 248 When this functionality is active, LilyPond adds hyperlinks to the PDF
 249 file.  These hyperlinks are sent to the web-browser, which opens a
 250 text-editor with the cursor in the right place.
 251
 252 To make this chain work, you should configure your PDF viewer to
 253 follow hyperlinks using the @file{lilypond-invoke-editor} script
 254 supplied with LilyPond.
 255
 256 For Xpdf on UNIX, the following should be present in
 257 @file{xpdfrc}@footnote{On UNIX, this file is found either in
 258 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
 259
 260 @example
 261 urlCommand     "lilypond-invoke-editor %s"
 262 @end example
 263
 264 The program @file{lilypond-invoke-editor} is a small helper
 265 program.  It will invoke an editor for the special @code{textedit}
 266 URIs, and run a web browser for others.  It tests the environment
 267 variable @code{EDITOR} for the following patterns,
 268
 269 @table @code
 270 @item emacs
 271   this will invoke
 272 @example
 273 emacsclient --no-wait +@var{line}:@var{column} @var{file}
 274 @end example
 275 @item vim
 276   this will invoke
 277 @example
 278 gvim --remote +:@var{line}:norm@var{char} @var{file}
 279 @end example
 280
 281 @item nedit
 282 this will invoke
 283 @example
 284   nc -noask +@var{line} @var{file}'
 285 @end example
 286 @end table
 287
 288 The environment variable @code{LYEDITOR} is used to override this.  It
 289 contains the command line to start the editor, where @code{%(file)s},
 290 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
 291 and line respectively.  The  setting
 292
 293 @example
 294 emacsclient --no-wait +%(line)s:%(column)s %(file)s
 295 @end example
 296
 297 @noindent
 298 for @code{LYEDITOR} is equivalent to the standard emacsclient
 299 invocation.
 300
 301
 302 @cindex file size, output
 303
 304 The point and click links enlarge the output files significantly.  For
 305 reducing the size of PDF and PS files, point and click may be switched
 306 off by issuing
 307
 308 @example
 309 \pointAndClickOff
 310 @end example
 311
 312 @noindent
 313 in a @file{.ly} file.  Point and click may be explicitly enabled with
 314
 315 @example
 316 \pointAndClickOn
 317 @end example
 318
 319 Alternately, you may disable point and click with a command-line
 320 option:
 321
 322 @example
 323 lilypond -dno-point-and-click file.ly
 324 @end example
 325
 326 @warning{You should always turn off point and click in any LilyPond
 327 files to be distributed to avoid including path information about
 328 your computer in the .pdf file, which can pose a security risk.}