Documentation/user/introduction.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @c This file is part of lilypond-learning.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.12.0"
  11
  12 @node Introduction
  13 @chapter Introduction
  14
  15 This chapter introduces readers to LilyPond and the
  16 documentation.
  17
  18 @menu
  19 * About the documentation::
  20 @end menu
  21
  22
  23 @node About the documentation
  24 @section About the documentation
  25
  26 This section explains the different portions of the documentation.
  27
  28 @cindex Learning Manual
  29 @cindex Music Glossary
  30 @cindex Notation Reference
  31 @cindex Application Usage
  32 @cindex Snippet List
  33 @cindex Internals Reference
  34
  35 @c leave these lines wrapping around.  It's some texinfo 4.12 thing. -gp
  36 @c This is actually a limitation of texi2html. -jm
  37 @menu
  38 * About the Learning Manual::  this manual introduces LilyPond, giving in-depth explanations of how to create notation.
  39 * About the Music Glossary::  this manual explains musical terms and gives translations of terms in other languages.
  40 * About the Notation Reference::  this manual is the main portion of the documentation.  It provides detailed information about creating notation.  This book assumes that the reader knows basic material covered in the Learning Manual and is familiar with the English musical terms presented in the Musical Glossary.
  41 * About the Application Usage::  this discusses the actual programs and operating system-specific issues.
  42 * About the Snippet List::  this is a collection of short LilyPond examples.
  43 * About the Internals Reference::  this document gives reference information about LilyPond's internal structures, which is required for constructing tweaks.
  44 * Other documentation::         there are a few other portions of the documentation, such as News items and the mailist archives.
  45 @end menu
  46
  47
  48 @node About the Learning Manual
  49 @unnumberedsubsec About the Learning Manual
  50
  51 @cindex Learning Manual
  52
  53 This book explains how to begin learning LilyPond, as well as
  54 explaining some key concepts in easy terms.  You should read these
  55 chapters in a linear fashion.
  56
  57 There is a paragraph @strong{See also} at the end of each section,
  58 which contains cross-references to other sections: you should not
  59 follow these cross-references at first reading; when you have read all
  60 of the Learning Manual, you may want to read some sections again and
  61 follow cross-references for further reading.
  62
  63 @itemize
  64
  65 @item
  66 @ref{Introduction}: explains the background and overall goal of
  67 LilyPond.
  68
  69 @item
  70 @ref{Tutorial}: gives a gentle introduction to typesetting music.
  71 First time users should start here.
  72
  73 @item
  74 @ref{Fundamental concepts}: explains some general concepts about
  75 the LilyPond file format.  If you are not certain where to place a
  76 command, read this chapter!
  77
  78 @item
  79 @ref{Tweaking output}: shows how to change the default engraving
  80 that LilyPond produces.
  81
  82 @item
  83 @ref{Working on LilyPond projects}: discusses practical uses of
  84 LilyPond and how to avoid some common problems.  Read this before
  85 undertaking large projects!
  86
  87 @end itemize
  88
  89 The Learning Manual also contains appendices which are not part of the
  90 recommended linear reading.  They may be useful for later
  91 viewing:
  92
  93 @itemize
  94
  95 @item
  96 @ref{Templates}: shows ready-made templates of LilyPond pieces.
  97 Just cut and paste a template into a file, add notes, and you're
  98 done!
  99
 100 @item
 101 @ref{Scheme tutorial}: presents a short introduction to Scheme,
 102 the programming language that music functions use.  This is
 103 material for advanced tweaks; many users never touch Scheme at
 104 all.
 105
 106 @end itemize
 107
 108
 109 @node About the Music Glossary
 110 @unnumberedsubsec About the Music Glossary
 111
 112 @cindex Music Glossary
 113 @cindex idiom
 114 @cindex jargon
 115 @cindex terminology
 116 @cindex foreign languages
 117 @cindex language
 118
 119 @rglosnamed{Top,Music glossary}
 120 this explains musical terms, and includes translations to various
 121 languages.  If you are not familiar with music notation or music
 122 terminology (especially if you are a non-native English speaker),
 123 it is highly advisable to consult the glossary.
 124
 125
 126 @node About the Notation Reference
 127 @unnumberedsubsec About the Notation Reference
 128
 129 @cindex Notation Reference
 130 @cindex appendices
 131 @cindex reference charts
 132 @cindex charts, reference
 133
 134 This book explains all the LilyPond commands which produce
 135 notation.  It assumes that readers are familiar with the concepts
 136 in the Learning Manual.
 137
 138 @itemize
 139
 140 @item
 141 @ruser{Musical notation}:
 142 discusses topics grouped by notation construct.  This section
 143 gives details about basic notation that will be useful in almost
 144 any notation project.
 145
 146 @item
 147 @ruser{Specialist notation}:
 148 discusses topics grouped by notation construct.  This section
 149 gives details about special notation that will only be useful for
 150 particular instrument (or vocal) groups.
 151
 152 @item
 153 @ruser{General input and output}:
 154 discusses general information about LilyPond input files and
 155 controlling output.
 156
 157 @item
 158 @ruser{Spacing issues}:
 159 discusses issues which affect the global output, such as selecting
 160 paper size or specifying page breaks.
 161
 162 @item
 163 @ruser{Changing defaults}:
 164 explains how to tweak LilyPond to produce exactly the notation you
 165 want.
 166
 167 @item
 168 @ruser{Interfaces for programmers}:
 169 explains how to create music functions with scheme.
 170
 171 @end itemize
 172
 173 The Notation Reference also contains appendices with useful
 174 reference charts.
 175
 176 @itemize
 177
 178 @item
 179 @ruser{Literature list}:
 180 contains a set of useful reference books for those who wish to
 181 know more on notation and engraving.
 182
 183 @item
 184 @ruser{Notation manual tables}:
 185 are a set of tables showing the chord names, MIDI instruments, a
 186 list of color names, and the Feta font.
 187
 188 @item
 189 @ruser{Cheat sheet}:
 190 is a handy reference of the most common LilyPond commands.
 191
 192 @item
 193 @ruser{LilyPond command index}:
 194 an index of all LilyPond @code{\commands}.
 195
 196 @item
 197 @ruser{LilyPond index}:
 198 a complete index.
 199
 200 @end itemize
 201
 202
 203 @node About the Application Usage
 204 @unnumberedsubsec About the Application Usage
 205
 206 @cindex Application Usage
 207 @cindex integrating LilyPond with other programs
 208
 209 This book explains how to execute the programs and how to integrate
 210 LilyPond notation with other programs.
 211
 212 @itemize
 213
 214 @item
 215 @rprogram{Install}:
 216 explains how to install LilyPond, including compilation if
 217 desired.
 218
 219 @item
 220 @rprogram{Setup}:
 221 describes how to configure your computer for optimum LilyPond
 222 usage, such as using special environments for certain text
 223 editors.
 224
 225 @item
 226 @rprogram{Running LilyPond}:
 227 shows how to run LilyPond and its helper programs.  In addition,
 228 this section explains how to upgrade input files from previous
 229 versions of LilyPond.
 230
 231 @item
 232 @rprogram{LilyPond-book}:
 233 explains the details behind creating documents with in-line music
 234 examples, like this manual.
 235
 236 @item
 237 @rprogram{Converting from other formats}:
 238 explains how to run the conversion programs.  These programs are
 239 supplied with the LilyPond package, and convert a variety of music
 240 formats to the @code{.ly} format.
 241
 242 @end itemize
 243
 244
 245 @node About the Snippet List
 246 @unnumberedsubsec About the Snippet List
 247
 248 @cindex snippets
 249 @cindex LSR
 250 @cindex Snippet List
 251 @cindex LilyPond Snippet Repository
 252
 253 @rlsrnamed{Top,LilyPond Snippet List}: this shows a
 254 selected set of LilyPond snippets from the
 255 @uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
 256 (LSR).  All the snippets are in the public domain.
 257
 258 Please note that this document is not an exact subset of LSR.  LSR
 259 is running a stable LilyPond version, so any snippet which
 260 demonstrates new features of a development version must be added
 261 separately.  These are stored in @file{input/new/} in the LilyPond
 262 source tree.
 263
 264 The list of snippets for each subsection of the Notation Reference are
 265 also linked from the @strong{See also} portion.
 266
 267
 268 @node About the Internals Reference
 269 @unnumberedsubsec About the Internals Reference
 270
 271 @cindex Internals Reference
 272
 273 @rinternalsnamed{Top,Internals Reference}: this is a set
 274 of heavily cross linked HTML pages which document the nitty-gritty
 275 details of each and every LilyPond class, object, and function.
 276 It is produced directly from the formatting definitions in the
 277 source code.
 278
 279 Almost all formatting functionality that is used internally is
 280 available directly to the user.  For example, most variables that
 281 control thickness values, distances, etc., can be changed in input
 282 files.  There are a huge number of formatting options, and all of
 283 them are described in this document.  Each section of the Notation
 284 Reference has a @b{See also} subsection, which refers to the
 285 generated documentation.  In the HTML document, these subsections
 286 have clickable links.
 287
 288
 289 @node Other documentation
 290 @unnumberedsubsec Other documentation
 291
 292 There are a number of other sources of information which may be
 293 very valuable.
 294
 295 @itemize
 296
 297 @item
 298 @ifhtml
 299 @ifset bigpage
 300 @uref{../topdocs/NEWS.html,News}:
 301 @end ifset
 302 @ifclear bigpage
 303 @uref{../../topdocs/NEWS.html,News}:
 304 @end ifclear
 305 @end ifhtml
 306 @ifnothtml
 307 News:
 308 @end ifnothtml
 309 this is a summary of important changes
 310 and new features in LilyPond since the previous version.
 311
 312 @item @uref{http://lists.gnu.org/archive/html/lilypond-user/, The
 313 lilypond-user mailist archives}: this is a collection of previous
 314 emails sent to the user list.  Many questions have been asked
 315 multiple times; there is a very good chance that if you have a
 316 question, the answer might be found in these archives.
 317
 318 @item @uref{http://lists.gnu.org/archive/html/lilypond-devel/, The
 319 lilypond-devel mailist archives}: this is a collection of previous
 320 emails sent to the developer's list.  The discussion here is more
 321 technical; if you have an advanced question about lilypond
 322 internals, the answer might be in these archives.
 323
 324 @item Embedded music fragments: in all HTML documents that have
 325 music fragments embedded, the exact LilyPond input that was used
 326 to produce that image can be viewed by clicking the image.
 327
 328 @item Init files: the location of the documentation files that are
 329 mentioned here can vary from system to system.  On occasion, this
 330 manual refers to initialization and example files.  Throughout this
 331 manual, we refer to input files relative to the top-directory of the
 332 source archive.  For example, @file{input/@/lsr/@/dirname/@/bla@/.ly}
 333 may refer to the file
 334 @file{lilypond@/2.x.y/@/input/@/lsr/@/dirname/@/bla@/.ly}.  On binary
 335 packages for the UNIX platform, the documentation and examples can
 336 typically be found somewhere below
 337 @file{/usr/@/share/@/doc/@/lilypond/}.  Initialization files, for
 338 example @file{scm/@/lily@/.scm}, or @file{ly/@/engraver@/-init@/.ly},
 339 are usually found in the directory @file{/usr/@/share/@/lilypond/}.
 340 For more details, see @ref{Other sources of information}.
 341
 342 @end itemize
 343