Documentation/general/manuals.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @ignore
   3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   4
   5     When revising a translation, copy the HEAD committish of the
   6     version that you are working on.  See TRANSLATION for details.
   7 @end ignore
   8
   9 @node Manuals
  10 @unnumbered Manuals
  11
  12 @divClass{heading-center}
  13 @heading Documentation for LilyPond 2.12.2
  14
  15 @divEnd
  16
  17 @divClass{column-center-top}
  18 @subheading Introduction
  19
  20 @itemize
  21
  22 @item @ref{Text input}:
  23 LilyPond is a @strong{text-based} music engraver.  If you are not
  24 familiar with this concept, please read this now!
  25
  26 @item @ref{Learning}:
  27 a @qq{must-read} gentle introduction to LilyPond.
  28
  29 @item @ref{Glossary}:
  30 @emph{(optional reading)}
  31 explains musical terms and gives translations for users unfamiliar
  32 with English musical terms.
  33
  34 @item @ref{Essay}:
  35 @emph{(optional reading)}
  36 background information about the engraving process and the
  37 aesthetics of 19th century music engraving.
  38
  39
  40 @end itemize
  41
  42 @divEnd
  43
  44 @divClass{column-left-top}
  45 @subheading Regular use
  46
  47 @itemize
  48
  49 @item @ref{Notation}:
  50 the main portion of the documentation; provides detailed
  51 information about creating notation.
  52
  53 @item @ref{Snippets}:
  54 short tricks, tips, and examples.
  55
  56 @item @ref{Usage}:
  57 discusses the actual programs and operating system-specific
  58 issues.
  59
  60 @end itemize
  61
  62 @divEnd
  63
  64
  65 @divClass{column-right-top}
  66 @subheading Infrequent Use
  67
  68 @itemize
  69
  70 @item @ref{FAQ}:
  71 links to the answers of Frequently Asked Questions.
  72
  73 @item @ref{Changes}:
  74 updates since the last major version.
  75
  76 @item @ref{Internals}:
  77 information about LilyPond's internal structures, which is
  78 required for constructing tweaks.
  79
  80 @end itemize
  81
  82 @divEnd
  83
  84
  85 @divClass{column-center-bottom}
  86 @subheading Other material
  87
  88 @itemize
  89
  90 @item @ref{Translated}:
  91 translation status for non-English readers.
  92
  93 @item @ref{All}:
  94 manuals for older versions and downloadable versions.
  95
  96 @item @ref{Development}:
  97 manuals for the unstable version.
  98
  99 @item @ref{FDL}:
 100 these manuals are published under the GNU Free Documentation
 101 License.
 102
 103 @end itemize
 104
 105 @divEnd
 106
 107
 108 @divClass{hide}
 109 @menu
 110 * Learning::             Learning.
 111 * Glossary::              Glossary.
 112 * Essay::                       Essay.
 113 * Notation::          Reference.
 114 * Usage::           Usage.
 115 * Snippets::                Snippets.
 116 * FAQ::                         FAQ.
 117 * Changes::                     NEWS.
 118 * Internals::         Internals.
 119 * Translated::          Translation.
 120 * All::                 All manuals.
 121 * FDL::                     Licence.
 122 @end menu
 123
 124 @divEnd
 125
 126
 127 @c TRANSLATORS: most of the text in this file came from
 128 @c LM 1.1 About the documentation  (before this section was
 129 @c removed in July 2009).
 130
 131 @node Learning
 132 @unnumberedsec Learning
 133
 134 @divClass{column-left-top}
 135 @subheading Learning manual
 136
 137 This book explains how to begin learning LilyPond, as well as
 138 explaining some key concepts in easy terms.  You should read these
 139 chapters in a linear fashion.
 140
 141 There is a paragraph @strong{See also} at the end of each section,
 142 which contains cross-references to other sections: you should not
 143 follow these cross-references at first reading.  When you have
 144 read all of the manual, you may want to read some sections again
 145 and follow those cross-references for more information.
 146 @divEnd
 147
 148 @divClass{column-right-top}
 149 @subheading Read it now
 150
 151 @itemize
 152
 153 @item @rlearningnamed{Top,Learning}:
 154 read this manual in the same format as this one.
 155
 156 @end itemize
 157 @divEnd
 158
 159 @divClass{column-center-bottom}
 160 @subheading Other formats
 161
 162 @divClass{keep-bullets}
 163 @itemize
 164
 165 @item @uref{../learning/index.html, Learning (split HTML)}:
 166 the manual is split between many HTML pages.
 167 @emph{(small download for each page)}
 168
 169 @item @uref{../learning-big-page.html, Learning (big HTML)}:
 170 read this manual as one huge HTML page.
 171 @emph{(large single download, around 10? Mb)}
 172
 173 @item @uref{../learning.pdf, learning.pdf}:
 174 download as a PDF file.
 175 @emph{(large single download, 2.8 Mb)}
 176
 177 @item @uref{FIXME, learning.info}:
 178 GNU info format for documentation.  FIXME, link broken.
 179
 180 @end itemize
 181 @divEnd
 182 @divEnd
 183
 184 @ignore
 185 @itemize
 186
 187 @item
 188 @item
 189 @rlearning{Tutorial}: gives a gentle introduction to typesetting music.
 190 First time users should start here.
 191
 192 @item
 193 @rlearning{Fundamental concepts}: explains some general concepts about
 194 the LilyPond file format.  If you are not certain where to place a
 195 command, read this chapter!
 196
 197 @item
 198 @rlearning{Tweaking output}: shows how to change the default engraving
 199 that LilyPond produces.
 200
 201 @item
 202 @rlearning{Working on LilyPond projects}: discusses practical uses of
 203 LilyPond and how to avoid some common problems.  Read this before
 204 undertaking large projects!
 205
 206 @end itemize
 207
 208 The Learning also contains appendices which are not part of the
 209 recommended linear reading.  They may be useful for later
 210 viewing:
 211
 212 @itemize
 213
 214 @item
 215 @rlearning{Templates}: shows ready-made templates of LilyPond pieces.
 216 Just cut and paste a template into a file, add notes, and you're
 217 done!
 218
 219 @item
 220 @rlearning{Scheme tutorial}: presents a short introduction to Scheme,
 221 the programming language that music functions use.  This is
 222 material for advanced tweaks; many users never touch Scheme at
 223 all.
 224
 225 @end itemize
 226 @end ignore
 227
 228
 229 @node Glossary
 230 @unnumberedsec Glossary
 231
 232 @rglosnamed{Top,Music glossary}
 233 this explains musical terms, and includes translations to various
 234 languages.  If you are not familiar with music notation or music
 235 terminology (especially if you are a non-native English speaker),
 236 it is highly advisable to consult the glossary.
 237
 238
 239 @node Essay
 240 @unnumberedsec Essay
 241
 242 blah
 243
 244
 245 @node Notation
 246 @unnumberedsec Notation
 247
 248 This book explains all the LilyPond commands which produce
 249 notation.
 250
 251 @warning{The Notation assumes that the reader knows
 252 basic material covered in the Learning and is familiar with
 253 the English musical terms presented in the Musical Glossary.}
 254
 255 @ignore
 256 @itemize
 257
 258 @item
 259 @ruser{Musical notation}:
 260 discusses topics grouped by notation construct.  This section
 261 gives details about basic notation that will be useful in almost
 262 any notation project.
 263
 264 @item
 265 @ruser{Specialist notation}:
 266 discusses topics grouped by notation construct.  This section
 267 gives details about special notation that will only be useful for
 268 particular instrument (or vocal) groups.
 269
 270 @item
 271 @ruser{General input and output}:
 272 discusses general information about LilyPond input files and
 273 controlling output.
 274
 275 @item
 276 @ruser{Spacing issues}:
 277 discusses issues which affect the global output, such as selecting
 278 paper size or specifying page breaks.
 279
 280 @item
 281 @ruser{Changing defaults}:
 282 explains how to tweak LilyPond to produce exactly the notation you
 283 want.
 284
 285 @item
 286 @ruser{Interfaces for programmers}:
 287 explains how to create music functions with scheme.
 288
 289 @end itemize
 290
 291 The Notation also contains appendices with useful
 292 reference charts.
 293
 294 @itemize
 295
 296 @item
 297 @ruser{Literature list}:
 298 contains a set of useful reference books for those who wish to
 299 know more on notation and engraving.
 300
 301 @item
 302 @ruser{Notation manual tables}:
 303 are a set of tables showing the chord names, MIDI instruments, a
 304 list of color names, and the Feta font.
 305
 306 @item
 307 @ruser{Cheat sheet}:
 308 is a handy reference of the most common LilyPond commands.
 309
 310 @item
 311 @ruser{LilyPond command index}:
 312 an index of all LilyPond @code{\commands}.
 313
 314 @item
 315 @ruser{LilyPond index}:
 316 a complete index.
 317
 318 @end itemize
 319 @end ignore
 320
 321
 322 @node Usage
 323 @unnumberedsec Usage
 324
 325 This book explains how to execute the programs and how to integrate
 326 LilyPond notation with other programs.
 327
 328 @ignore
 329 @itemize
 330
 331 @item
 332 @rprogram{Install}:
 333 explains how to install LilyPond, including compilation if
 334 desired.
 335
 336 @item
 337 @rprogram{Setup}:
 338 describes how to configure your computer for optimum LilyPond
 339 usage, such as using special environments for certain text
 340 editors.
 341
 342 @item
 343 @rprogram{Running LilyPond}:
 344 shows how to run LilyPond and its helper programs.  In addition,
 345 this section explains how to upgrade input files from previous
 346 versions of LilyPond.
 347
 348 @item
 349 @rprogram{LilyPond-book}:
 350 explains the details behind creating documents with in-line music
 351 examples, like this manual.
 352
 353 @item
 354 @rprogram{Converting from other formats}:
 355 explains how to run the conversion programs.  These programs are
 356 supplied with the LilyPond package, and convert a variety of music
 357 formats to the @code{.ly} format.
 358
 359 @end itemize
 360 @end ignore
 361
 362
 363 @node Snippets
 364 @unnumberedsec Snippets
 365
 366 @rlsrnamed{Top,LilyPond Snippets}: this shows a
 367 selected set of LilyPond snippets from the
 368 @uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
 369 (LSR).  All the snippets are in the public domain.
 370
 371 Please note that this document is not an exact subset of LSR.  LSR
 372 is running a stable LilyPond version, so any snippet which
 373 demonstrates new features of a development version must be added
 374 separately.  These are stored in @file{input/new/} in the LilyPond
 375 source tree.
 376
 377 The list of snippets for each subsection of the Notation are
 378 also linked from the @strong{See also} portion.
 379
 380
 381 @node FAQ
 382 @unnumberedsec FAQ
 383
 384 @warning{to be moved into the actual Documentation/ in master)}
 385
 386
 387 @subheading Where are the graphical canvas, menus, and toolbars?
 388
 389 LilyPond requires you to write music as text.  Please read about
 390 our @ref{Text input}.
 391
 392
 393 @subheading There's a lot of documentation!  Do I need to read it?
 394
 395 You need to read the @ref{Learning}.  As for the rest of
 396 documentation, you only need to read the sections which discuss
 397 the notation that you wish to create.
 398
 399
 400 @subheading That's still a lot of reading!  Is it worth it?
 401
 402 Please decide for yourself; the reasons why you might want to use
 403 LilyPond are given in the @ref{Introduction}.
 404
 405
 406 @subheading Something isn't working!  How do I fix it?
 407
 408 This is explained in @@ref@{FIXME LM or AU x.y@}.
 409
 410
 411 @subheading Why do you change the syntax?
 412
 413 This is explained in @@ref@{FIXME AU x.y@}.
 414
 415
 416 @node Changes
 417 @unnumberedsec Changes
 418
 419 previous-named "NEWS" doc.
 420
 421 this is a summary of important changes
 422 and new features in LilyPond since the previous version.
 423
 424
 425
 426 @node Internals
 427 @unnumberedsec Internals
 428
 429 @rinternalsnamed{Top,Internals}: this is a set
 430 of heavily cross linked HTML pages which document the nitty-gritty
 431 details of each and every LilyPond class, object, and function.
 432 It is produced directly from the formatting definitions in the
 433 source code.
 434
 435 Almost all formatting functionality that is used internally is
 436 available directly to the user.  For example, most variables that
 437 control thickness values, distances, etc., can be changed in input
 438 files.  There are a huge number of formatting options, and all of
 439 them are described in this document.  Each section of the Notation
 440 Reference has a @b{See also} subsection, which refers to the
 441 generated documentation.  In the HTML document, these subsections
 442 have clickable links.
 443
 444
 445
 446 @node Translated
 447 @unnumberedsec Translated
 448
 449 blah
 450
 451
 452 @node All
 453 @unnumberedsec All
 454
 455 @divClass{column-left-top}
 456 @subheading Downloadable versions
 457
 458 FIXME: compare tarball vs. zip size, ask about windows users
 459 dealing with tarballs (both gz and bz2), etc.
 460
 461 @divClass{keep-bullets}
 462 @itemize
 463
 464 @item html-split zip
 465
 466 @item html-big zip
 467
 468 @item pdf zip
 469
 470 @item info zip maybe?!?!
 471
 472 @end itemize
 473
 474 @divEnd
 475 @divEnd
 476
 477 @divClass{column-right-top}
 478 @subheading Previous stable versions
 479
 480 @divClass{keep-bullets}
 481 @itemize
 482
 483 @item @uref{http://lilypond.org/doc/v2.12/Documentation/,
 484 LilyPond 2.12 Documentation}
 485
 486 @item @uref{http://lilypond.org/doc/v2.10/Documentation/,
 487 LilyPond 2.10 Documentation}
 488
 489 @item @uref{http://lilypond.org/doc/v2.8/Documentation/,
 490 LilyPond 2.8 Documentation}
 491
 492 @item FIXME etc.
 493
 494 @end itemize
 495
 496 @divEnd
 497 @divEnd
 498
 499
 500 @node FDL
 501 @unnumberedsec FDL
 502
 503 @divClass{column-center-top}
 504 @subheading Documentation license
 505
 506 The documentation for GNU LilyPond is published under the GNU Free
 507 Documentation License.  An introduction to this license, and our
 508 reasons for choosing it, is given in @ref{Freedom}.
 509
 510 @divEnd
 511
 512 @divClass{column-center-bottom}
 513 @subheading GNU Free Documentation License 1.1
 514
 515 @include fdl.itexi
 516
 517 @divEnd
 518
 519