doc/README

   1  opus_libre -- README
   2
   3  (c) 2008-2011 Valentin Villenave <valentin@villenave.net>
   4     opus_libre is a free framework for GNU LilyPond: you may
   5  redistribute it and/or modify it under the terms of the GNU
   6  General Public License as published by the Free Software
   7  Foundation, either version 3 of the License, or (at your option)
   8  any later version.
   9     This program is distributed WITHOUT ANY WARRANTY; without
  10  even the implied warranty of MERCHANTABILITY or FITNESS FOR A
  11  PARTICULAR PURPOSE.You should have received a copy of the GNU
  12  General Public License along with this program (typically in the
  13  share/doc/ directory).If not, see http://www.gnu.org/licenses/
  14
  15
  16 ** what it is **
  17 opus_libre is a framework for the GNU LilyPond music notation software.
  18
  19 LilyPond is a GNU Free software that is both powerful and simple to
  20 learn, and that you can download on http://www.lilypond.org.
  21 It runs on most modern Operating Systems, and has been
  22 ported for various architectures.
  23
  24
  25 ** principle **
  26 opus_libre is designed with portability in mind, to make it easier to
  27 create new scores as well as to integrate existing ones within the
  28 framework.  It should also eventually have support for graphic themes,
  29 input/edition languages choice, automatic scores inclusion using
  30 predefined skeletons, etc.
  31
  32
  33 ** usage **
  34 You may use opus_libre by adding your music in an appropriately-named
  35 separate subdirectory of the scores/ directory.  If you plan on
  36 distributing the source code of score (which I hope you'll do),
  37 please remember to add your name, copyright, and license to all of
  38 your score's source files.  Using opus_libre does not mandate you to
  39 publish your score under a free license (it's okay to be afraid, we've
  40 all been there), but even if you don't, please be a good citizen and
  41 at least have a look at http://freedomdefined.org...
  42
  43 (Or http://artlibre.org if you happen to speak French :-)
  44
  45
  46 ** how does it work? **
  47 Well, let me walk you through the file tree, that should give you
  48 a few pointers.
  49
  50 opus_libre follows the *nix Filesystem Hierarchy Standard, which
  51 you should be familiar with if you use a GNU/Linux or BSD system.
  52
  53 Think of the opus_libre root directory as / or /usr/ (kind of both,
  54 actually. Oh well).  Which means that:
  55   - /bin contains "applications" (well, in this case, LilyPond macros)
  56          that you can use to make your life (well, at least your music
  57          typesetting) a bit easier.
  58   - doc/ You're reading it. Duh.
  59     - snippets/ Short snippets, intended to be merged with upstream
  60                 documentation or the LSR.  Eventually. If I care.
  61   - /lib contains "libraries" (in this case, Scheme functions) that
  62          you normally don't have to deal with directly.  As long as your
  63          entry file (the one you'll feed to LilyPond, typically main.ly)
  64          has something like \include "lib/include.ly", everything else will
  65          be done automatically.
  66   - /etc contains "system-wide settings" (in this case, definitions
  67          that will be useful no matter what score you want to compile). Which,
  68          in turn, includes
  69     - ly.conf (the main configuration file)
  70     - ly.conf.d/ (additional conf files)
  71     - locale/ (you know what I mean)
  72     - skel/ (.lyskel skeleton files that will give tell opus_libre
  73             how to "vertically" organize your score: staffs, staff groups,
  74             lyrics, etc.)
  75   - /out is the directory where your compiled PDF (png, svg, midi,...) files
  76          will appear.
  77   - /scores is where you put your music (we've covered that bit, haven't we?).
  78             Please note that *everything* that lives in / (meaning, the
  79             opus_libre root directory) may be overriden by what's in
  80             score/yourscore/.  Think of your score directory as the /usr/local/
  81             directory, where you can have customized macros, local settings,
  82             skeletons, themes, language files, whatever you might need that's
  83             specific to a particular score.
  84   - /share contains resources that aren't algorithmic (that's not entirely
  85            true however, as we'll see):
  86     - fonts/ Fancier fonts than Lily's Century SchoolBook or whatever are the
  87              default fonts on your system.
  88     - images/ Cute little thingies you might want on your scores.  Mostly Postscript
  89               code (though pixmaps aren't entirely off the table yet).
  90     - themes/ This is where you can select graphic themes (provided that different
  91               themes actually exist, of course).  Layout, Paper variables are
  92               also set here.  The default theme is loaded anyway, so that
  93               selecting an additional theme will only override what's needed.
  94
  95 More documentation will be added later; for now, you may learn more
  96 about LilyPond on its official website or on the community website
  97 http://www.lilynet.net.
  98
  99
 100 ** what it does (and what it doesn't do) **
 101 opus_libre does try to be clever so you don't have to be.
 102
 103 For instance, music variables can be named using your native language
 104 or English; another example is the swiss-knife-like \make command,
 105 that you can provide with either the name of an instrument, a piece of
 106 your score, a list of pieces or special arguments!
 107
 108 What opus_libre also tries to do is allow you to easily override
 109 *anything* you might think of.  We've seen that your score directory may
 110 contain local overrides; any .ly file (even your main.ly, although that's
 111 not recommended) can also set definitions.  All in all, there are quite a
 112 few places where you can set or override a setting, in order of precedence:
 113   - any .ly file
 114   - your local score.ly file
 115   - main.ly
 116   - any local .conf file
 117   - any etc/ly.conf.d/* conf file
 118   - the etc/ly.conf file
 119
 120 All of this comes at a cost: what opus_libre will NOT do is
 121 make your music compile faster.  All files are processed, all
 122 variables are defined no matter what will actually be used;
 123 many variables are even defined several times because of the
 124 override paradigm.  So let's face it: there IS a memory overhead,
 125 that can even be quite substantial (even if all you want to do is
 126 compile only the flute part of one movement of a symphony,
 127 opus_libre will still load the whole full score into RAM!), and
 128 there IS an additional delay compared to the amount of time
 129 GNU LilyPond usually takes.
 130
 131
 132 ** history **
 133 opus_libre originated with the Opera Libre project, a large music score
 134 of mine that was entirely written, published, performed and recorded
 135 using only Free Software.  Although I had been coding quite a lot of
 136 macros and functions for this project, all of this remained tightly
 137 connected with this particular score, on a (relatively speaking) low
 138 level.  This is why I started the opus_libre project, in an attempt
 139 to make the framework more abstract, portable and extensible.
 140
 141
 142 ** Who am I? **
 143 I'm a 26-years-old French composer, GNU LilyPond contributor and
 144 free software activist.  But mostly, that's just a fancy way of
 145 saying that I'm your average computer geek.
 146
 147 My own music is stored on various git repositories,
 148 for instance my Opera Libre project may be found on
 149 http://repo.or.cz/w/opera_libre.git.
 150 I also have a personal website on http://valentin.villenave.net.
 151
 152 Please feel free to stop by and let me know about your thoughts!
 153
 154    - Valentin Villenave, September 2010.