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.38"
  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 @end menu
 109
 110 @node Emacs mode
 111 @subsection Emacs mode
 112
 113 Emacs has a @file{lilypond-mode}, which provides keyword
 114 autocompletion, indentation, LilyPond specific parenthesis matching
 115 and syntax coloring, handy compile short-cuts and reading LilyPond
 116 manuals using Info.  If @file{lilypond-mode} is not installed on your
 117 platform, see below.
 118
 119 An Emacs mode for entering music and running LilyPond is contained in
 120 the source archive in the @file{elisp} directory.  Do @command{make
 121 install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
 122 should be placed to @var{load-path}@file{/site-start.d/} or appended
 123 to your @file{~/.emacs} or @file{~/.emacs.el}.
 124
 125 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
 126 your @var{load-path} by appending the following line (as modified) to your
 127 @file{~/.emacs}
 128
 129 @c any reason we do not advise:  (push "~/site-lisp" load-path)
 130 @example
 131 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 132 @end example
 133
 134
 135 @node Vim mode
 136 @subsection Vim mode
 137
 138 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
 139 along with syntax coloring tools.  A Vim mode for entering music and
 140 running LilyPond is contained in the source archive in @code{$VIM}
 141 directory.
 142
 143 The LilyPond file type is detected if the file
 144 @file{~/.vim/filetype.vim} has the following content
 145
 146 @example
 147 if exists("did_load_filetypes")
 148   finish
 149 endif
 150 augroup filetypedetect
 151   au! BufNewFile,BufRead *.ly           setf lilypond
 152 augroup END
 153 @end example
 154
 155 Please include this path by appending the following line to your
 156 @file{~/.vimrc}
 157
 158 @example
 159 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
 160 @end example
 161
 162 @noindent
 163 where $@{LILYPOND_VERSION@} is your LilyPond version.  If LilyPond was not
 164 installed in @file{/usr/local/}, then change this path accordingly.
 165
 166
 167 @node jEdit
 168 @subsection jEdit
 169
 170 Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit}
 171 text editor, LilyPondTool is the most feature-rich text-based tool for
 172 editing LilyPond scores.  Its features include a Document Wizard with
 173 lyrics support to set up documents easier, and embedded PDF viewer with
 174 advanced point-and-click support.  For screenshots, demos and
 175 installation instructions, visit
 176 @uref{http://lilypondtool@/.organum@/.hu}
 177
 178
 179 @node TexShop
 180 @subsection TexShop
 181
 182 The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop}
 183 editor for MacOS@tie{}X can be extended to run LilyPond, lilypond-book and
 184 convert-ly from within the editor, using the extensions available at
 185 @uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}.
 186
 187
 188 @node TextMate
 189 @subsection TextMate
 190
 191 There is a LilyPond bundle for TextMate.  It may be installed by running
 192
 193 @example
 194 mkdir -p /Library/Application\ Support/TextMate/Bundles
 195 cd /Library/Application\ Support/TextMate/Bundles
 196 svn co http://macromates.com/svn/Bundles/trunk/Bundles/Lilypond.tmbundle/
 197 @end example
 198
 199
 200
 201 @node Point and click
 202 @section Point and click
 203 @cindex point and click
 204
 205
 206 Point and click lets you find notes in the input by clicking on them
 207 in the PDF viewer.  This makes it easier to find input that causes
 208 some error in the sheet music.
 209
 210 When this functionality is active, LilyPond adds hyperlinks to the PDF
 211 file.  These hyperlinks are sent to the web-browser, which opens a
 212 text-editor with the cursor in the right place.
 213
 214 To make this chain work, you should configure your PDF viewer to
 215 follow hyperlinks using the @file{lilypond-invoke-editor} script
 216 supplied with LilyPond.
 217
 218 For Xpdf on UNIX, the following should be present in
 219 @file{xpdfrc}@footnote{On UNIX, this file is found either in
 220 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
 221
 222 @example
 223 urlCommand     "lilypond-invoke-editor %s"
 224 @end example
 225
 226 The program @file{lilypond-invoke-editor} is a small helper
 227 program.  It will invoke an editor for the special @code{textedit}
 228 URIs, and run a web browser for others.  It tests the environment
 229 variable @code{EDITOR} for the following patterns,
 230
 231 @table @code
 232 @item emacs
 233   this will invoke
 234 @example
 235 emacsclient --no-wait +@var{line}:@var{column} @var{file}
 236 @end example
 237 @item vim
 238   this will invoke
 239 @example
 240 gvim --remote +:@var{line}:norm@var{char} @var{file}
 241 @end example
 242
 243 @item nedit
 244 this will invoke
 245 @example
 246   nc -noask +@var{line} @var{file}'
 247 @end example
 248 @end table
 249
 250 The environment variable @code{LYEDITOR} is used to override this.  It
 251 contains the command line to start the editor, where @code{%(file)s},
 252 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
 253 and line respectively.  The  setting
 254
 255 @example
 256 emacsclient --no-wait +%(line)s:%(column)s %(file)s
 257 @end example
 258
 259 @noindent
 260 for @code{LYEDITOR} is equivalent to the standard emacsclient
 261 invocation.
 262
 263
 264 @cindex file size, output
 265
 266 The point and click links enlarge the output files significantly.  For
 267 reducing the size of PDF and PS files, point and click may be switched
 268 off by issuing
 269
 270 @example
 271 #(ly:set-option 'point-and-click #f)
 272 @end example
 273
 274 @noindent
 275 in a @file{.ly} file.  Alternately, you may pass this as an command-line
 276 option
 277
 278 @example
 279 lilypond -dno-point-and-click file.ly
 280 @end example
 281