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 @node Setup
  11 @chapter Setup
  12
  13 This chapter discusses how to set up LilyPond to integrate with various
  14 programs.
  15
  16 @menu
  17 * Notes for the MacOS X app::
  18 * Text editor support::
  19 * Point and click::
  20 @end menu
  21
  22
  23 @node Notes for the MacOS X app
  24 @section Notes for the MacOS X app
  25
  26 The scripts (such as lilypond-book, convert-ly, abc2ly, and even
  27 lilypond itself) are also
  28 included inside MacOS X .app. They can be run from the command line by
  29 invoking them directly, e.g.
  30
  31 @example
  32 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
  33 @end example
  34
  35 @noindent
  36 The same is true of the other scripts in that directory, including
  37 lilypond-book, convert-ly, abc2ly, etc.
  38
  39 Alternatively, you may create scripts which add the path
  40 automatically.  Create a directory to store these scripts,
  41
  42 @example
  43 mkdir -p ~/bin
  44 cd ~/bin
  45 @end example
  46
  47 Create a file called @code{lilypond} which contains
  48
  49 @example
  50 exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
  51 @end example
  52
  53 Create similar files @code{lilypond-book}, @code{convert-ly}, and
  54 any other helper programs you use (@code{abc2ly}, @code{midi2ly},
  55 etc).  Simply replace the @code{bin/lilypond} with
  56 @code{bin/convert-ly} (or other program name) in the above file.
  57
  58 Make the file executable,
  59
  60 @example
  61 chmod u+x lilypond
  62 @end example
  63
  64 Now, add this directory to your path.  Modify (or create)
  65 a file called @code{.profile} in your home directory such that it contains
  66
  67 @example
  68 export PATH=$PATH:~/bin
  69 @end example
  70
  71 @noindent
  72 This file should end with a blank line.
  73
  74 Note that @var{path/to} will generally be @code{/Applications/}.
  75
  76
  77 @node Text editor support
  78 @section Text editor support
  79
  80 @cindex editors
  81 @cindex vim
  82 @cindex emacs
  83 @cindex modes, editor
  84 @cindex syntax coloring
  85 @cindex coloring, syntax
  86
  87 There is support from different text editors for LilyPond.
  88
  89 @menu
  90 * Emacs mode::
  91 * Vim mode::
  92 * LilyPondTool::
  93 * TexShop::
  94 * TextMate::
  95 @end menu
  96
  97 @node Emacs mode
  98 @subsection Emacs mode
  99
 100 Emacs has a @file{lilypond-mode}, which provides keyword
 101 autocompletion, indentation, LilyPond specific parenthesis matching
 102 and syntax coloring, handy compile short-cuts and reading LilyPond
 103 manuals using Info.  If @file{lilypond-mode} is not installed on your
 104 platform, see below.
 105
 106 An Emacs mode for entering music and running LilyPond is contained in
 107 the source archive in the @file{elisp} directory.  Do @command{make
 108 install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
 109 should be placed to @var{load-path}@file{/site-start.d/} or appended
 110 to your @file{~/.emacs} or @file{~/.emacs.el}.
 111
 112 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
 113 your @var{load-path} by appending the following line (as modified) to your
 114 @file{~/.emacs}
 115
 116 @c any reason we do not advise:  (push "~/site-lisp" load-path)
 117 @example
 118 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 119 @end example
 120
 121
 122 @node Vim mode
 123 @subsection Vim mode
 124
 125 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
 126 along with syntax coloring tools.  A Vim mode for entering music and
 127 running LilyPond is contained in the source archive in @code{$VIM}
 128 directory.
 129
 130 The LilyPond file type is detected if the file
 131 @file{~/.vim/filetype.vim} has the following content
 132
 133 @example
 134 if exists("did_load_filetypes")
 135   finish
 136 endif
 137 augroup filetypedetect
 138   au! BufNewFile,BufRead *.ly           setf lilypond
 139 augroup END
 140 @end example
 141
 142 Please include this path by appending the following line to your
 143 @file{~/.vimrc}
 144
 145 @example
 146 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
 147 @end example
 148
 149 @noindent
 150 where $@{LILYPOND_VERSION@} is your lilypond version.  If Lilypond was not
 151 installed in @file{/usr/local/}, then change this path accordingly.
 152
 153
 154 @node LilyPondTool
 155 @subsection LilyPondTool
 156
 157 Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit}
 158 text editor, LilyPondTool is the most feature-rich text-based tool for
 159 editing LilyPond scores.  Its features include a Document Wizard with
 160 lyrics support to set up documents easier, and embedded PDF viewer with
 161 advanced point-and-click support.  For screenshots, demos and
 162 installation instructions, visit
 163 @uref{http://lilypondtool@/.organum@/.hu}
 164
 165
 166 @node TexShop
 167 @subsection TexShop
 168
 169 The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop}
 170 editor for Mac OS X can be extended to run LilyPond, lilypond-book and
 171 convert-ly from within the editor, using the extensions available at
 172 @uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}.
 173
 174
 175 @node TextMate
 176 @subsection TextMate
 177
 178 There is a LilyPond bundle for TextMate.  It may be installed by running
 179
 180 @example
 181 mkdir -p /Library/Application\ Support/TextMate/Bundles
 182 cd /Library/Application\ Support/TextMate/Bundles
 183 svn co http://macromates.com/svn/Bundles/trunk/Bundles/Lilypond.tmbundle/
 184 @end example
 185
 186
 187
 188 @node Point and click
 189 @section Point and click
 190 @cindex point and click
 191
 192
 193 Point and click lets you find notes in the input by clicking on them
 194 in the PDF viewer.  This makes it easier to find input that causes
 195 some error in the sheet music.
 196
 197 When this functionality is active, LilyPond adds hyperlinks to the PDF
 198 file. These hyperlinks are sent to the web-browser, which opens a
 199 text-editor with the cursor in the right place.
 200
 201 To make this chain work, you should configure your PDF viewer to
 202 follow hyperlinks using the @file{lilypond-invoke-editor} script
 203 supplied with LilyPond.
 204
 205 For Xpdf on Unix, the following should be present in
 206 @file{xpdfrc}@footnote{On unix, this file is found either in
 207 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
 208
 209 @example
 210 urlCommand     "lilypond-invoke-editor %s"
 211 @end example
 212
 213 The program @file{lilypond-invoke-editor} is a small helper
 214 program. It will invoke an editor for the special @code{textedit}
 215 URIs, and run a web browser for others.  It tests the environment
 216 variable @code{EDITOR} for the following patterns,
 217
 218 @table @code
 219 @item emacs
 220   this will invoke
 221 @example
 222 emacsclient --no-wait +@var{line}:@var{column} @var{file}
 223 @end example
 224 @item vim
 225   this will invoke
 226 @example
 227 gvim --remote +:@var{line}:norm@var{char} @var{file}
 228 @end example
 229
 230 @item nedit
 231 this will invoke
 232 @example
 233   nc -noask +@var{line} @var{file}'
 234 @end example
 235 @end table
 236
 237 The environment variable @code{LYEDITOR} is used to override this. It
 238 contains the command line to start the editor, where @code{%(file)s},
 239 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
 240 and line respectively. The  setting
 241
 242 @example
 243 emacsclient --no-wait +%(line)s:%(column)s %(file)s
 244 @end example
 245
 246 @noindent
 247 for @code{LYEDITOR} is equivalent to the standard emacsclient
 248 invocation.
 249
 250
 251 @cindex file size, output
 252
 253 The point and click links enlarge the output files significantly. For
 254 reducing the size of PDF and PS files, point and click may be switched
 255 off by issuing
 256
 257 @example
 258 #(ly:set-option 'point-and-click #f)
 259 @end example
 260
 261 @noindent
 262 in a @file{.ly} file.  Alternately, you may pass this as an command-line
 263 option
 264
 265 @example
 266 lilypond -dno-point-and-click file.ly
 267 @end example
 268