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