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 was "INSTALL - compiling and installing GNU LilyPond"
  11 @node Setup
  12 @chapter Setup
  13
  14 This chapter discusses how to set up LilyPond to integrate with various
  15 programs.
  16
  17 @menu
  18 * Notes for the MacOS X app::
  19 * Text editor support::
  20 * Point and click::
  21 @end menu
  22
  23
  24 @node Notes for the MacOS X app
  25 @section Notes for the MacOS X app
  26
  27 The scripts (such as lilypond-book, convert-ly, abc2ly, and even
  28 lilypond itself) are also
  29 included inside MacOS X .app. They can be run from the command line by
  30 invoking them directly, e.g.
  31
  32 @example
  33 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
  34 @end example
  35
  36 @noindent
  37 The same is true of the other scripts in that directory, including
  38 lilypond-book, convert-ly, abc2ly, etc.
  39
  40 Alternatively, you may create scripts which add the path
  41 automatically.  Create a directory to store these scripts,
  42
  43 @example
  44 mkdir -p ~/bin
  45 cd ~/bin
  46 @end example
  47
  48 Create a file called @code{lilypond} which contains
  49
  50 @example
  51 exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
  52 @end example
  53
  54 Create similar files @code{lilypond-book}, @code{convert-ly}, and
  55 any other helper programs you use (@code{abc2ly}, @code{midi2ly},
  56 etc).  Simply replace the @code{bin/lilypond} with
  57 @code{bin/convert-ly} (or other program name) in the above file.
  58
  59 Make the file executable,
  60
  61 @example
  62 chmod u+x lilypond
  63 @end example
  64
  65 Now, add this directory to your path.  Modify (or create)
  66 a file called @code{.profile} in your home directory such that it contains
  67
  68 @example
  69 export PATH=$PATH:~/bin
  70 @end example
  71
  72 @noindent
  73 This file should end with a blank line.
  74
  75 Note that @var{path/to} will generally be @code{/Applications/}.
  76
  77
  78 @node Text editor support
  79 @section Text editor support
  80
  81 @cindex editors
  82 @cindex vim
  83 @cindex emacs
  84 @cindex modes, editor
  85 @cindex syntax coloring
  86 @cindex coloring, syntax
  87
  88 There is support from different text editors for LilyPond.
  89
  90 @menu
  91 * Emacs mode::
  92 * Vim mode::
  93 * LilyPondTool::
  94 * TexShop::
  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
 176
 177 @node Point and click
 178 @section Point and click
 179 @cindex point and click
 180
 181
 182 Point and click lets you find notes in the input by clicking on them
 183 in the PDF viewer.  This makes it easier to find input that causes
 184 some error in the sheet music.
 185
 186 When this functionality is active, LilyPond adds hyperlinks to the PDF
 187 file. These hyperlinks are sent to the web-browser, which opens a
 188 text-editor with the cursor in the right place.
 189
 190 To make this chain work, you should configure your PDF viewer to
 191 follow hyperlinks using the @file{lilypond-invoke-editor} script
 192 supplied with LilyPond.
 193
 194 For Xpdf on Unix, the following should be present in
 195 @file{xpdfrc}@footnote{On unix, this file is found either in
 196 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
 197
 198 @example
 199 urlCommand     "lilypond-invoke-editor %s"
 200 @end example
 201
 202 The program @file{lilypond-invoke-editor} is a small helper
 203 program. It will invoke an editor for the special @code{textedit}
 204 URIs, and run a web browser for others.  It tests the environment
 205 variable @code{EDITOR} for the following patterns,
 206
 207 @table @code
 208 @item emacs
 209   this will invoke
 210 @example
 211 emacsclient --no-wait +@var{line}:@var{column} @var{file}
 212 @end example
 213 @item vim
 214   this will invoke
 215 @example
 216 gvim --remote +:@var{line}:norm@var{char} @var{file}
 217 @end example
 218
 219 @item nedit
 220 this will invoke
 221 @example
 222   nc -noask +@var{line} @var{file}'
 223 @end example
 224 @end table
 225
 226 The environment variable @code{LYEDITOR} is used to override this. It
 227 contains the command line to start the editor, where @code{%(file)s},
 228 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
 229 and line respectively. The  setting
 230
 231 @example
 232 emacsclient --no-wait +%(line)s:%(column)s %(file)s
 233 @end example
 234
 235 @noindent
 236 for @code{LYEDITOR} is equivalent to the standard emacsclient
 237 invocation.
 238
 239
 240 @cindex file size, output
 241
 242 The point and click links enlarge the output files significantly. For
 243 reducing the size of PDF and PS files, point and click may be switched
 244 off by issuing
 245
 246 @example
 247 #(ly:set-option 'point-and-click #f)
 248 @end example
 249
 250 @noindent
 251 in a @file{.ly} file.  Alternately, you may pass this as an command-line
 252 option
 253
 254 @example
 255 lilypond -dno-point-and-click file.ly
 256 @end example
 257