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 @version
  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{Usage}:
  54 discusses the actual programs and operating system-specific
  55 issues.
  56
  57 @item @ref{Snippets}:
  58 short tricks, tips, and examples.
  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
 185 @node Glossary
 186 @unnumberedsec Glossary
 187
 188 @divClass{column-left-top}
 189 @subheading Glossary
 190
 191 This explains musical terms, and includes translations to various
 192 languages.  If you are not familiar with music notation or music
 193 terminology (especially if you are a non-native English speaker),
 194 it is highly advisable to consult the glossary.
 195
 196 @divEnd
 197
 198 @divClass{column-right-top}
 199 @subheading Read it now
 200
 201 @itemize
 202
 203 @item @rglosnamed{Top,Music glossary}:
 204 read this manual in the same format as this one.
 205
 206 @end itemize
 207 @divEnd
 208
 209 @divClass{column-center-bottom}
 210 @subheading Other formats
 211
 212 @divClass{keep-bullets}
 213 @itemize
 214
 215 @item @uref{glossary/index.html, Glossary (split HTML)}:
 216 the manual is split between many HTML pages.
 217 @emph{(small download for each page)}
 218
 219 @item @uref{glossary-big-page.html, Glossay (big HTML)}:
 220 read this manual as one huge HTML page.
 221 @emph{(large single download, around 10? Mb)}
 222
 223 @item @uref{glossary.pdf, glossary.pdf}:
 224 download as a PDF file.
 225 @emph{(large single download, 2.8 Mb)}
 226
 227 @item @uref{FIXME, glossary.info}:
 228 GNU info format for documentation.  FIXME, link broken.
 229
 230 @end itemize
 231 @divEnd
 232 @divEnd
 233
 234
 235 @node Essay
 236 @unnumberedsec Essay
 237
 238 @divClass{column-center-top}
 239 @subheading Essay
 240
 241 This book gives a brief history of music typography, followed by
 242 an examination of LilyPond's engraving techniques.  A comparison
 243 between LilyPond and other music engraving systems is given.
 244
 245 @warning{The detailed typographical examples are easier to analyze
 246 in the PDF version due to its higher resolution.}
 247
 248 @divEnd
 249
 250 @divClass{column-right-top}
 251 @subheading Read it now
 252
 253 @itemize
 254
 255 @item @ressaynamed{Top,Essay}:
 256 read this manual in the same format as this one.
 257
 258 @end itemize
 259 @divEnd
 260
 261 @divClass{column-center-bottom}
 262 @subheading Other formats
 263
 264 @divClass{keep-bullets}
 265 @itemize
 266
 267 @item @uref{essay/index.html, Essay (split HTML)}:
 268 the manual is split between many HTML pages.
 269 @emph{(small download for each page)}
 270
 271 @item @uref{essay-big-page.html, Essay (big HTML)}:
 272 read this manual as one huge HTML page.
 273 @emph{(large single download, around FIXME? Mb)}
 274
 275 @item @uref{essay.pdf, essay.pdf}:
 276 download as a PDF file.
 277 @emph{(large single download, FIXME? Mb)}
 278
 279 @item @uref{FIXME, essay.info}:
 280 GNU info format for documentation.  FIXME, link broken.
 281
 282 @end itemize
 283 @divEnd
 284 @divEnd
 285
 286
 287 @node Notation
 288 @unnumberedsec Notation
 289
 290 @divClass{column-left-top}
 291 @subheading Notation reference
 292
 293 This book explains all the LilyPond commands which produce
 294 notation.
 295
 296 @warning{The Notation reference assumes that the reader knows
 297 basic material covered in the Learning manual and is familiar with
 298 the English musical terms presented in the Musical Glossary.}
 299
 300 @divEnd
 301
 302 @divClass{column-right-top}
 303 @subheading Read it now
 304
 305 @itemize
 306
 307 @item @rusernamed{Top,Notation}:
 308 read this manual in the same format as this one.
 309
 310 @end itemize
 311 @divEnd
 312
 313 @divClass{column-center-bottom}
 314 @subheading Other formats
 315
 316 @divClass{keep-bullets}
 317 @itemize
 318
 319 @item @uref{notation/index.html, Notation (split HTML)}:
 320 the manual is split between many HTML pages.
 321 @emph{(small download for each page)}
 322
 323 @item @uref{notation-big-page.html, Notation (big HTML)}:
 324 read this manual as one huge HTML page.
 325 @emph{(large single download, around 10? Mb)}
 326
 327 @item @uref{notation.pdf, notation.pdf}:
 328 download as a PDF file.
 329 @emph{(large single download, 2.8 Mb)}
 330
 331 @item @uref{FIXME, notation.info}:
 332 GNU info format for documentation.  FIXME, link broken.
 333
 334 @end itemize
 335 @divEnd
 336 @divEnd
 337
 338
 339 @node Usage
 340 @unnumberedsec Usage
 341
 342 @divClass{column-left-top}
 343 @subheading Usage manual
 344
 345 This book explains how to execute the programs, how to integrate
 346 LilyPond notation with other programs, and suggests @qq{best
 347 practices} for efficient use.  It is recommended reading before
 348 attempting any large projects.
 349 @divEnd
 350
 351 @divClass{column-right-top}
 352 @subheading Read it now
 353
 354 @itemize
 355
 356 @item @rprogramnamed{Top,Usage}:
 357 read this manual in the same format as this one.
 358
 359 @end itemize
 360 @divEnd
 361
 362 @divClass{column-center-bottom}
 363 @subheading Other formats
 364
 365 @divClass{keep-bullets}
 366 @itemize
 367
 368 @item @uref{usage/index.html, Usage (split HTML)}:
 369 the manual is split between many HTML pages.
 370 @emph{(small download for each page)}
 371
 372 @item @uref{usage-big-page.html, Usage (big HTML)}:
 373 read this manual as one huge HTML page.
 374 @emph{(large single download, around 10? Mb)}
 375
 376 @item @uref{usage.pdf, usage.pdf}:
 377 download as a PDF file.
 378 @emph{(large single download, 2.8 Mb)}
 379
 380 @item @uref{FIXME, lilypond-usage.info}:
 381 GNU info format for documentation.  FIXME, link broken.
 382
 383 @end itemize
 384 @divEnd
 385 @divEnd
 386
 387
 388 @node Snippets
 389 @unnumberedsec Snippets
 390
 391 @divClass{column-left-top}
 392 @subheading Snippets
 393
 394 This shows a selected set of LilyPond snippets from the
 395 @uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
 396 (LSR).  All the snippets are in the public domain.
 397
 398 Please note that this document is not an exact subset of LSR.  LSR
 399 is running a stable LilyPond version, so any snippet which
 400 demonstrates new features of a development version must be added
 401 separately.  These are stored in @file{input/new/} in the LilyPond
 402 source tree.
 403
 404 The list of snippets for each subsection of the Notation are also
 405 linked from the @strong{See also} portion.
 406 @divEnd
 407
 408 @divClass{column-right-top}
 409 @subheading Read it now
 410
 411 @itemize
 412
 413 @item @rlsrnamed{Top,Snippets}:
 414 read this manual in the same format as this one.
 415
 416 @end itemize
 417 @divEnd
 418
 419 @divClass{column-center-bottom}
 420 @subheading Other formats
 421
 422 @divClass{keep-bullets}
 423 @itemize
 424
 425 @item @uref{snippets/index.html, Snippets (split HTML)}:
 426 the manual is split between many HTML pages.
 427 @emph{(small download for each page)}
 428
 429 @item @uref{snippets-big-page.html, Snippets (big HTML)}:
 430 read this manual as one huge HTML page.
 431 @emph{(large single download, around 10? Mb)}
 432
 433 @item @uref{snippets.pdf, snippets.pdf}:
 434 download as a PDF file.
 435 @emph{(large single download, 2.8 Mb)}
 436
 437 @item @uref{FIXME, snippets.info}:
 438 GNU info format for documentation.  FIXME, link broken.
 439
 440 @end itemize
 441 @divEnd
 442 @divEnd
 443
 444
 445 @node FAQ
 446 @unnumberedsec FAQ
 447
 448 @divClass{column-center-top}
 449 @subheading Introductory questions
 450
 451 @subsubheading Where are the graphical canvas, menus, and toolbars?
 452
 453 LilyPond requires you to write music as text.  Please read about
 454 our @ref{Text input}.
 455
 456
 457 @subsubheading There's a lot of documentation!  Do I need to read it?
 458
 459 You need to read the @ref{Learning, Learning manual}.  As for the
 460 rest of documentation, you only need to read the sections which
 461 discuss the notation that you wish to create.
 462
 463
 464 @subsubheading That's still a lot of reading!  Is it worth it?
 465
 466 Please decide for yourself; the reasons why you might want to use
 467 LilyPond are given in the @ref{Introduction}.
 468
 469 @divEnd
 470
 471 @divClass{column-center-bottom}
 472 @subheading Usage questions
 473
 474 @subsubheading Something isn't working!  How do I fix it?
 475
 476 This is explained in @rprogram{Troubleshooting}.
 477
 478
 479 @subsubheading Why do you change the syntax?
 480
 481 This is explained in @rprogram{Why does the syntax change?}.
 482
 483 @divEnd
 484
 485
 486 @node Changes
 487 @unnumberedsec Changes
 488
 489 @divClass{column-left-top}
 490 @subheading Changes
 491
 492 This is a summary of important changes and new features in
 493 LilyPond since the previous stable version.
 494
 495 @divEnd
 496
 497 @divClass{column-right-top}
 498 @subheading Read it now
 499
 500 @itemize
 501
 502 @item @rchangesnamed{Top,Changes}:
 503 read this manual in the same format as this one.
 504
 505 @end itemize
 506 @divEnd
 507
 508 @divClass{column-center-bottom}
 509 @subheading Other formats
 510
 511 @divClass{keep-bullets}
 512 @itemize
 513
 514 @c Changes isn't available as a split manual.
 515 @c  (maybe it should be, but it isn't so far)
 516 @c @item @uref{changes/index.html, Changes (split HTML)}:
 517 @c the manual is split between many HTML pages.
 518 @c @emph{(small download for each page)}
 519
 520 @c @item @uref{changes-big-page.html, Changes (big HTML)}:
 521 @c read this manual as one huge HTML page.
 522 @c @emph{(large single download, around 10? Mb)}
 523
 524 @item @uref{changes.html, Changes}:
 525 read this manual as a HTML page.
 526
 527 @item @uref{changes.pdf, changes.pdf}:
 528 download as a PDF file.
 529 @emph{(small single download, 0.5 ?? Mb)}
 530
 531 @item @uref{FIXME, changes.info}:
 532 GNU info format for documentation.  FIXME, link broken.
 533
 534 @end itemize
 535 @divEnd
 536 @divEnd
 537
 538
 539
 540 @node Internals
 541 @unnumberedsec Internals
 542
 543 @divClass{column-left-top}
 544 @subheading Internals reference
 545
 546 This is a set of heavily cross linked HTML pages which document
 547 the nitty-gritty details of each and every LilyPond class, object,
 548 and function.  It is produced directly from the formatting
 549 definitions in the source code.
 550
 551 Almost all formatting functionality that is used internally is
 552 available directly to the user.  For example, most variables that
 553 control thickness values, distances, etc., can be changed in input
 554 files.  There are a huge number of formatting options, and all of
 555 them are described in this document.  Each section of the Notation
 556 Reference has a @b{See also} subsection, which refers to the
 557 generated documentation.  In the HTML document, these subsections
 558 have clickable links.
 559
 560 @divEnd
 561
 562 @divClass{column-right-top}
 563 @subheading Read it now
 564
 565 @itemize
 566
 567 @item @rinternalsnamed{Top,Internals}:
 568 read this manual in the same format as this one.
 569
 570 @end itemize
 571 @divEnd
 572
 573 @divClass{column-center-bottom}
 574 @subheading Other formats
 575
 576 @divClass{keep-bullets}
 577 @itemize
 578
 579 @item @uref{internals/index.html, Internals (split HTML)}:
 580 the manual is split between many HTML pages.
 581 @emph{(small download for each page)}
 582
 583 @item @uref{internals-big-page.html, Internals (big HTML)}:
 584 read this manual as one huge HTML page.
 585 @emph{(large single download, around 10? Mb)}
 586
 587 @item @uref{internals.pdf, internals.pdf}:
 588 download as a PDF file.
 589 @emph{(large single download, 2.8 Mb)}
 590
 591 @item @uref{FIXME, internals.info}:
 592 GNU info format for documentation.  FIXME, link broken.
 593
 594 @end itemize
 595 @divEnd
 596 @divEnd
 597
 598
 599
 600 @node Translated
 601 @unnumberedsec Translated
 602
 603 @divClass{column-center-bottom}
 604 @subheading Translation status
 605
 606 TODO: clean up / prettify
 607
 608 @uref{translations.html}.
 609
 610 @divEnd
 611
 612
 613 @node All
 614 @unnumberedsec All
 615
 616 @divClass{column-left-top}
 617 @subheading Downloadable versions
 618
 619 FIXME: compare tarball vs. zip size, ask about windows users
 620 dealing with tarballs (both gz and bz2), etc.
 621
 622 @divClass{keep-bullets}
 623 @itemize
 624
 625 @item html-split zip
 626
 627 @item html-big zip
 628
 629 @item pdf zip
 630
 631 @item info zip maybe?!?!
 632
 633 @end itemize
 634
 635 @divEnd
 636 @divEnd
 637
 638 @divClass{column-right-top}
 639 @subheading Previous stable versions
 640
 641 @divClass{keep-bullets}
 642 @itemize
 643
 644 @item @uref{http://lilypond.org/doc/v2.12/Documentation/,
 645 LilyPond 2.12 Documentation}
 646
 647 @item @uref{http://lilypond.org/doc/v2.10/Documentation/,
 648 LilyPond 2.10 Documentation}
 649
 650 @item @uref{http://lilypond.org/doc/v2.8/Documentation/,
 651 LilyPond 2.8 Documentation}
 652
 653 @item FIXME etc.
 654
 655 @end itemize
 656
 657 @divEnd
 658 @divEnd
 659
 660
 661 @node FDL
 662 @unnumberedsec FDL
 663
 664 @divClass{column-center-top}
 665 @subheading Documentation license
 666
 667 The documentation for GNU LilyPond is published under the GNU Free
 668 Documentation License.  An introduction to this license, and our
 669 reasons for choosing it, is given in @ref{Freedom}.
 670
 671 @divEnd
 672
 673 @divClass{column-center-bottom}
 674 @subheading GNU Free Documentation License 1.1
 675
 676 @include fdl.itexi
 677
 678 @divEnd
 679
 680