Begin lilypond-program reworking.

[lilypond.git] / Documentation / user / setup.itely

diff --git a/Documentation/user/setup.itely b/Documentation/user/setup.itely
new file mode 100644 (file)
index 0000000..7ac1c50
--- /dev/null
+++ b/Documentation/user/setup.itely
@@ -0,0 +1,137 @@
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond-program.tely
+@ignore
+    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+    When revising a translation, copy the HEAD committish of the
+    version that you are working on.  See TRANSLATION for details.
+@end ignore
+
+@c was "INSTALL - compiling and installing GNU LilyPond"
+@node Setup
+@chapter Setup
+
+This chapter discusses how to set up LilyPond to integrate with various
+programs.
+
+@menu
+* Notes for the MacOS X app::   
+* Text editor support::         
+@end menu
+
+
+@node Notes for the MacOS X app
+@section Notes for the MacOS X app
+
+The scripts (such as lilypond-book, convert-ly, abc2ly, and even
+lilypond itself) are also
+included inside MacOS X .app. They can be run from the command line by
+invoking them directly, e.g.
+
+@example
+@var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
+@end example
+
+@noindent
+The same is true of the other scripts in that directory, including
+lilypond-book, convert-ly, abc2ly, etc.
+
+Alternatively, you may create scripts which add the path
+automatically.  Create a directory to store these scripts,
+
+@example
+mkdir -p ~/bin
+cd ~/bin
+@end example
+
+Create a file called @code{lilypond} which contains
+
+@example
+exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
+@end example
+
+Create similar files @code{lilypond-book}, @code{convert-ly}, and
+any other helper programs you use (@code{abc2ly}, @code{midi2ly},
+etc).  Simply replace the @code{bin/lilypond} with
+@code{bin/convert-ly} (or other program name) in the above file.
+
+Make the file executable,
+
+@example
+chmod u+x lilypond
+@end example
+
+Now, add this directory to your path.  Modify (or create)
+a file called @code{.profile} in your home directory such that it contains
+
+@example
+export PATH=$PATH:~/bin
+@end example
+
+@noindent
+This file should end with a blank line.
+
+Note that @var{path/to} will generally be @code{/Applications/}.
+
+
+@node Text editor support
+@section Text editor support
+
+@menu
+* Emacs mode::                  
+* Vim mode::                    
+@end menu
+
+@node Emacs mode
+@subsection Emacs mode
+
+An Emacs mode for entering music and running LilyPond is contained in
+the source archive in the @file{elisp} directory.  Do @command{make
+install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
+should be placed to @var{load-path}@file{/site-start.d/} or appended
+to your @file{~/.emacs} or @file{~/.emacs.el}.
+
+As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
+your @var{load-path} by appending the following line (as modified) to your
+@file{~/.emacs}
+@c any reason we do not advise:  (push "~/site-lisp" load-path)
+@quotation
+@example
+(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
+@end example
+@end quotation
+
+
+@node Vim mode
+@subsection Vim mode
+
+A Vim mode for entering music and running LilyPond is contained in the
+source archive in @code{$VIM} directory.
+
+The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c
+has the following content
+@quotation
+@example
+if exists("did_load_filetypes")
+  finish
+endif
+augroup filetypedetect
+  au! BufNewFile,BufRead *.ly           setf lilypond
+augroup END
+@end example
+@end quotation
+
+Please include this path by appending the following line to your
+@file{~/.vimrc}
+
+@quotation
+@example
+set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
+@end example
+@end quotation
+
+@noindent
+where $@{LILYPOND_VERSION@} is your lilypond version.  If Lilypond was not
+installed in @file{/usr/local/}, then change this path accordingly.
+
+