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