Documentation/web/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 @c TODO: do we want these links to be in larger text / bold ?   CSS.
  18
  19 @c if you change this page, also change All.
  20 @divClass{column-center-top}
  21 @subheading Introduction
  22
  23 @itemize
  24
  25 @item @ref{Text input}:
  26 LilyPond is a @strong{text-based} music engraver.  If you are not
  27 familiar with this concept, please read this now!
  28
  29 @item @ref{Learning}:
  30 a @qq{must-read} gentle introduction to LilyPond.
  31
  32 @item @ref{Glossary}:
  33 @emph{(optional reading)}
  34 explains musical terms and gives translations for users unfamiliar
  35 with English musical terms.
  36
  37 @item @ref{Essay}:
  38 @emph{(optional reading)}
  39 background information about the engraving process and the
  40 aesthetics of 19th century music engraving.
  41
  42
  43 @end itemize
  44
  45 @divEnd
  46
  47 @divClass{column-left-top}
  48 @subheading Regular use
  49
  50 @itemize
  51
  52 @item @ref{Notation}:
  53 the main portion of the documentation; provides detailed
  54 information about creating notation.
  55
  56 @item @ref{Usage}:
  57 discusses the actual programs and operating system-specific
  58 issues.
  59
  60 @item @ref{Snippets}:
  61 short tricks, tips, and examples.
  62
  63 @end itemize
  64
  65 @divEnd
  66
  67
  68 @divClass{column-right-top}
  69 @subheading Infrequent Use
  70
  71 @itemize
  72
  73 @item @ref{Web}:
  74 this document.
  75
  76 @item @ref{FAQ}:
  77 links to the answers of Frequently Asked Questions.
  78
  79 @item @ref{Changes}:
  80 updates since the last major version.
  81
  82 @item @ref{Extend}:
  83 programming fancy tweaks in LilyPond.
  84
  85 @item @ref{Internals}:
  86 information about LilyPond's internal structures, which is
  87 required for constructing tweaks.
  88
  89 @end itemize
  90
  91 @divEnd
  92
  93
  94 @divClass{column-center-bottom}
  95 @subheading Other material
  96
  97 @itemize
  98
  99 @item @ref{Translated}:
 100 translation status for non-English readers.
 101
 102 @item @ref{All}:
 103 quick links, downloadable manuals, and old manuals.
 104
 105 @item @ref{Development}:
 106 manuals for the unstable version.
 107
 108 @item @ref{FDL}:
 109 these manuals are published under the GNU Free Documentation
 110 License.
 111
 112 @end itemize
 113
 114 @divEnd
 115
 116
 117 @divClass{hide}
 118 @menu
 119 * Learning::             Learning.
 120 * Glossary::              Glossary.
 121 * Essay::                       Essay.
 122 * Notation::          Reference.
 123 * Usage::           Usage.
 124 * Snippets::                Snippets.
 125 * Web::                      Web.
 126 * FAQ::                         FAQ.
 127 * Changes::                     NEWS.
 128 * Extend::         Programming.
 129 * Internals::         Internals.
 130 * Translated::          Translation.
 131 * All::                 All manuals.
 132 * FDL::                     Licence.
 133 @end menu
 134
 135 @divEnd
 136
 137
 138 @c TRANSLATORS: most of the text in this file came from
 139 @c LM 1.1 About the documentation  (before this section was
 140 @c removed in July 2009).
 141
 142 @node Learning
 143 @unnumberedsec Learning
 144
 145 @divClass{column-left-top}
 146 @subheading Learning manual
 147
 148 This book explains how to begin learning LilyPond, as well as
 149 explaining some key concepts in easy terms.  You should read these
 150 chapters in a linear fashion.
 151
 152 There is a paragraph @strong{See also} at the end of each section,
 153 which contains cross-references to other sections: you should not
 154 follow these cross-references at first reading.  When you have
 155 read all of the manual, you may want to read some sections again
 156 and follow those cross-references for more information.
 157 @divEnd
 158
 159 @divClass{column-right-bottom}
 160
 161 @docLinks{Learning, learning,
 162   @rlearningnamed{Top,Learning},
 163   @manualStableLearningSplit,
 164   @manualStableLearningBig, 1.5 Mb,
 165   @manualStableLearningPdf, 3 Mb}
 166
 167 @divEnd
 168
 169
 170 @node Glossary
 171 @unnumberedsec Glossary
 172
 173 @divClass{column-left-top}
 174 @subheading Glossary
 175
 176 This explains musical terms, and includes translations to various
 177 languages.  If you are not familiar with music notation or music
 178 terminology (especially if you are a non-native English speaker),
 179 it is highly advisable to consult the glossary.
 180
 181 @divEnd
 182
 183 @divClass{column-right-bottom}
 184
 185 @docLinks{Music glossary, music-glossary,
 186   @rglosnamed{Top,Music glossary},
 187   @manualStableGlossarySplit,
 188   @manualStableGlossaryBig, 1 Mb,
 189   @manualStableGlossaryPdf, 1.5 Mb}
 190
 191 @divEnd
 192
 193
 194 @node Essay
 195 @unnumberedsec Essay
 196
 197 @divClass{column-left-top}
 198 @subheading Essay
 199
 200 This book gives a brief history of music typography, followed by
 201 an examination of LilyPond's engraving techniques.  A comparison
 202 between LilyPond and other music engraving systems is given.
 203
 204 @warning{The detailed typographical examples are easier to analyze
 205 in the PDF version due to its higher resolution.}
 206
 207 @divEnd
 208
 209 @divClass{column-right-bottom}
 210 @subheading Read it
 211
 212 @itemize
 213
 214 @item @ressaynamed{Top,Essay}:
 215 read this manual in the same format as this one.
 216
 217 @end itemize
 218
 219 @subheading All formats
 220
 221 @divClass{keep-bullets}
 222 @itemize
 223
 224 @item @uref{../essay/index.html, Essay (split HTML)}:
 225 the manual is split between many HTML pages.
 226 @*@ @ @emph{(small download for each page)}
 227
 228 @item @uref{../essay-big-page.html, Essay (big HTML)}:
 229 read this manual as one huge HTML page.
 230 @*@ @ @emph{(large single download, 2 Mb)}
 231
 232 @item @uref{../essay.pdf, essay.pdf}:
 233 download as a PDF file.
 234 @*@ @ @emph{(large single download, 2.5 Mb)}
 235
 236 @c @item @uref{../TODO, essay.info}:
 237 @c GNU info format for documentation.  TODO, link broken.
 238
 239 @end itemize
 240 @divEnd
 241 @divEnd
 242
 243
 244 @node Notation
 245 @unnumberedsec Notation
 246
 247 @divClass{column-left-top}
 248 @subheading Notation reference
 249
 250 This book explains all the LilyPond commands which produce
 251 notation.
 252
 253 @warning{The Notation reference assumes that the reader knows
 254 basic material covered in the Learning manual and is familiar with
 255 the English musical terms presented in the Musical Glossary.}
 256
 257 @divEnd
 258
 259 @divClass{column-right-bottom}
 260 @subheading Read it
 261
 262 @itemize
 263
 264 @item @rusernamed{Top,Notation}:
 265 read this manual in the same format as this one.
 266
 267 @end itemize
 268
 269 @subheading All formats
 270
 271 @divClass{keep-bullets}
 272 @itemize
 273
 274 @item @uref{../notation/index.html, Notation (split HTML)}:
 275 the manual is split between many HTML pages.
 276 @*@ @ @emph{(small download for each page)}
 277
 278 @item @uref{../notation-big-page.html, Notation (big HTML)}:
 279 read this manual as one huge HTML page.
 280 @*@ @ @emph{(large single download, 7 Mb)}
 281
 282 @item @uref{../notation.pdf, notation.pdf}:
 283 download as a PDF file.
 284 @*@ @ @emph{(large single download, 18 Mb)}
 285
 286 @c @item @uref{../TODO, notation.info}:
 287 @c GNU info format for documentation.  TODO, link broken.
 288
 289 @end itemize
 290 @divEnd
 291 @divEnd
 292
 293
 294 @node Usage
 295 @unnumberedsec Usage
 296
 297 @divClass{column-left-top}
 298 @subheading Usage manual
 299
 300 This book explains how to execute the programs, how to integrate
 301 LilyPond notation with other programs, and suggests @qq{best
 302 practices} for efficient use.  It is recommended reading before
 303 attempting any large projects.
 304 @divEnd
 305
 306 @divClass{column-right-bottom}
 307 @subheading Read it
 308
 309 @itemize
 310
 311 @item @rprogramnamed{Top,Usage}:
 312 read this manual in the same format as this one.
 313
 314 @end itemize
 315
 316 @subheading All formats
 317
 318 @divClass{keep-bullets}
 319 @itemize
 320
 321 @item @uref{../usage/index.html, Usage (split HTML)}:
 322 the manual is split between many HTML pages.
 323 @*@ @ @emph{(small download for each page)}
 324
 325 @item @uref{../usage-big-page.html, Usage (big HTML)}:
 326 read this manual as one huge HTML page.
 327 @*@ @ @emph{(large single download, 300 kb)}
 328
 329 @item @uref{../usage.pdf, usage.pdf}:
 330 download as a PDF file.
 331 @*@ @ @emph{(large single download, 400 kb)}
 332
 333 @c @item @uref{../TODO, lilypond-usage.info}:
 334 @c GNU info format for documentation.  TODO, link broken.
 335
 336 @end itemize
 337 @divEnd
 338 @divEnd
 339
 340
 341 @node Snippets
 342 @unnumberedsec Snippets
 343
 344 @divClass{column-left-top}
 345 @subheading Snippets
 346
 347 This shows a selected set of LilyPond snippets from the
 348 @uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
 349 (LSR).  All the snippets are in the public domain.
 350
 351 Please note that this document is not an exact subset of LSR.  LSR
 352 is running a stable LilyPond version, so any snippet which
 353 demonstrates new features of a development version must be added
 354 separately.  These are stored in @file{input/new/} in the LilyPond
 355 source tree.
 356
 357 The list of snippets for each subsection of the Notation are also
 358 linked from the @strong{See also} portion.
 359 @divEnd
 360
 361 @divClass{column-right-bottom}
 362 @subheading Read it
 363
 364 @itemize
 365
 366 @item @rlsrnamed{Top,Snippets}:
 367 read this manual in the same format as this one.
 368
 369 @end itemize
 370
 371 @subheading All formats
 372
 373 @divClass{keep-bullets}
 374 @itemize
 375
 376 @item @uref{../snippets/index.html, Snippets (split HTML)}:
 377 the manual is split between many HTML pages.
 378 @*@ @ @emph{(small download for each page)}
 379
 380 @item @uref{../snippets-big-page.html, Snippets (big HTML)}:
 381 read this manual as one huge HTML page.
 382 @*@ @ @emph{(large single download, 2.5 Mb)}
 383
 384 @item @uref{../snippets.pdf, snippets.pdf}:
 385 download as a PDF file.
 386 @*@ @ @emph{(large single download, 8 Mb)}
 387
 388 @c @item @uref{../TODO, snippets.info}:
 389 @c GNU info format for documentation.  TODO, link broken.
 390
 391 @end itemize
 392 @divEnd
 393 @divEnd
 394
 395
 396 @node Web
 397 @unnumberedsec Web
 398
 399 @divClass{column-left-top}
 400 @subheading Web
 401
 402 This manual supplies general information about LilyPond.  It also
 403 contains information about various community forums, bug
 404 reporting, and development.
 405
 406 @divEnd
 407
 408 @divClass{column-right-bottom}
 409 @subheading Read it
 410
 411 @itemize
 412
 413 @item @rweb{Top,Web}:
 414 read this manual in the same format as this one.
 415
 416 @end itemize
 417
 418 @subheading All formats
 419
 420 @divClass{keep-bullets}
 421 @itemize
 422
 423 @item @uref{../web/index.html, Web (split HTML)}:
 424 the manual is split between many HTML pages.
 425 @*@ @ @emph{(small download for each page)}
 426
 427 @item @uref{../web-big-page.html, Web (big HTML)}:
 428 read this manual as one huge HTML page.
 429 @*@ @ @emph{(large single download, 1 Mb)}
 430
 431 @item @uref{../web.pdf, web.pdf}:
 432 download as a PDF file.
 433 @*@ @ @emph{(large single download, 2 Mb)}
 434
 435 @c @item @uref{../TODO, web.info}:
 436 @c GNU info format for documentation.  TODO, link broken.
 437
 438 @end itemize
 439 @divEnd
 440 @divEnd
 441
 442
 443
 444 @node FAQ
 445 @unnumberedsec FAQ
 446
 447 @divClass{column-center-top}
 448 @subheading Introductory questions
 449
 450 @subsubheading Where are the graphical canvas, menus, and toolbars?
 451
 452 LilyPond requires you to write music as text.  Please read about
 453 our @ref{Text input}.
 454
 455
 456 @subsubheading There's a lot of documentation!  Do I need to read it?
 457
 458 You need to read the @ref{Learning, Learning manual}.  As for the
 459 rest of documentation, you only need to read the sections which
 460 discuss the notation that you wish to create.
 461
 462
 463 @subsubheading That's still a lot of reading!  Is it worth it?
 464
 465 Please decide for yourself; the reasons why you might want to use
 466 LilyPond are given in the @ref{Introduction}.
 467
 468 @divEnd
 469
 470 @divClass{column-center-bottom}
 471 @subheading Usage questions
 472
 473 @subsubheading Something isn't working!  How do I fix it?
 474
 475 This is explained in @rprogram{Troubleshooting}.
 476
 477
 478 @subsubheading Why do you change the syntax?
 479
 480 This is explained in @rprogram{Why does the syntax change?}.
 481
 482 @divEnd
 483
 484
 485 @node Changes
 486 @unnumberedsec Changes
 487
 488 @divClass{column-left-top}
 489 @subheading Changes
 490
 491 This is a summary of important changes and new features in
 492 LilyPond since the previous stable version.
 493
 494 @divEnd
 495
 496 @divClass{column-right-bottom}
 497 @subheading Read it
 498
 499 @itemize
 500
 501 @item @rchangesnamed{Top,Changes}:
 502 read this manual in the same format as this one.
 503
 504 @end itemize
 505
 506 @subheading All formats
 507
 508 @divClass{keep-bullets}
 509 @itemize
 510
 511 @item @uref{../changes/index.html, Changes (split HTML)}:
 512 the manual is split between many HTML pages.
 513 @*@ @ @emph{(small download for each page)}
 514
 515 @item @uref{../changes-big-page.html, Changes (big HTML)}:
 516 read this manual as one huge HTML page.
 517 @*@ @ @emph{(large single download, 6 kb)}
 518
 519 @item @uref{../changes.pdf, changes.pdf}:
 520 download as a PDF file.
 521 @*@ @ @emph{(small single download, 200 kb)}
 522
 523 @c @item @uref{../TODO, changes.info}:
 524 @c GNU info format for documentation.  TODO, link broken.
 525
 526 @end itemize
 527 @divEnd
 528 @divEnd
 529
 530
 531 @node Extend
 532 @unnumberedsec Extend
 533
 534 @divClass{column-left-top}
 535 @subheading Extend LilyPond
 536
 537 This manual explains how to write extensions to LilyPond.
 538
 539 @divEnd
 540
 541 @divClass{column-right-bottom}
 542 @subheading Read it
 543
 544 @itemize
 545
 546 @item @rextendnamed{Top,Extend}:
 547 read this manual in the same format as this one.
 548
 549 @end itemize
 550
 551 @subheading All formats
 552
 553 @divClass{keep-bullets}
 554 @itemize
 555
 556 @item @uref{../extending/index.html, Extend (split HTML)}:
 557 the manual is split between many HTML pages.
 558 @*@ @ @emph{(small download for each page)}
 559
 560 @item @uref{../extending-big-page.html, Extend (big HTML)}:
 561 read this manual as one huge HTML page.
 562 @*@ @ @emph{(large single download, 200 kb)}
 563
 564 @item @uref{../extending.pdf, extending.pdf}:
 565 download as a PDF file.
 566 @*@ @ @emph{(large single download, 400 kb)}
 567
 568 @c @item @uref{../TODO, extending.info}:
 569 @c GNU info format for documentation.  TODO, link broken.
 570
 571 @end itemize
 572 @divEnd
 573 @divEnd
 574
 575
 576 @node Internals
 577 @unnumberedsec Internals
 578
 579 @divClass{column-left-top}
 580 @subheading Internals reference
 581
 582 This is a set of heavily cross linked HTML pages which document
 583 the nitty-gritty details of each and every LilyPond class, object,
 584 and function.  It is produced directly from the formatting
 585 definitions in the source code.
 586
 587 Almost all formatting functionality that is used internally is
 588 available directly to the user.  For example, most variables that
 589 control thickness values, distances, etc., can be changed in input
 590 files.  There are a huge number of formatting options, and all of
 591 them are described in this document.  Each section of the Notation
 592 Reference has a @b{See also} subsection, which refers to the
 593 generated documentation.  In the HTML document, these subsections
 594 have clickable links.
 595
 596 @divEnd
 597
 598 @divClass{column-right-bottom}
 599 @subheading Read it
 600
 601 @itemize
 602
 603  @rinternalsnamed{Top,Internals}:
 604 read this manual in the same format as this one.
 605
 606 @end itemize
 607
 608 @subheading All formats
 609
 610 @divClass{keep-bullets}
 611 @itemize
 612
 613 @item @uref{../internals/index.html, Internals (split HTML)}:
 614 the manual is split between many HTML pages.
 615 @*@ @ @emph{(small download for each page)}
 616
 617 @item @uref{../internals-big-page.html, Internals (big HTML)}:
 618 read this manual as one huge HTML page.
 619 @*@ @ @emph{(large single download, 2.5 Mb)}
 620
 621 @item @uref{../internals.pdf, internals.pdf}:
 622 download as a PDF file.
 623 @*@ @ @emph{(large single download, 2.8 Mb)}
 624
 625 @c @item @uref{../TODO, internals.info}:
 626 @c GNU info format for documentation.  TODO, link broken.
 627
 628 @end itemize
 629 @divEnd
 630 @divEnd
 631
 632
 633
 634 @node Translated
 635 @unnumberedsec Translated
 636
 637 @divClass{column-center-bottom}
 638 @subheading Translation status
 639
 640 TODO: clean up / prettify
 641
 642 @uref{../translations.html}.
 643
 644 @divEnd
 645
 646
 647 @node All
 648 @unnumberedsec All
 649
 650 @divClass{heading-center}
 651 @heading Documentation quick links
 652
 653 Links to other formats of these manuals can be found in
 654 @ref{Manuals}.
 655
 656 @divEnd
 657
 658 @c this should match the (main) manual page.
 659 @divClass{column-center-top}
 660 @subheading Introduction
 661
 662 @itemize
 663
 664 @item @rlearningnamed{Top,Learning}:
 665 a @qq{must-read} gentle introduction to LilyPond.
 666
 667 @item @rglosnamed{Top,Glossary}:
 668 @emph{(optional reading)}
 669 explains musical terms and gives translations for users unfamiliar
 670 with English musical terms.
 671
 672 @item @ressaynamed{Top,Essay}:
 673 @emph{(optional reading)}
 674 background information about the engraving process and the
 675 aesthetics of 19th century music engraving.
 676
 677 @end itemize
 678
 679 @divEnd
 680
 681 @divClass{column-left-top}
 682 @subheading Regular use
 683
 684 @itemize
 685
 686 @item @rusernamed{Top,Notation}:
 687 the main portion of the documentation; provides detailed
 688 information about creating notation.
 689
 690 @item @rprogramnamed{Top,Usage}:
 691 discusses the actual programs and operation system-specific
 692 issues.
 693
 694 @item @rlsrnamed{Top,Snippets}:
 695 short tricks, tips, and examples.
 696
 697 @end itemize
 698
 699 @divEnd
 700
 701
 702 @divClass{column-right-top}
 703 @subheading Infrequent Use
 704
 705 @itemize
 706
 707 @item @ref{FAQ}:
 708 links to answers of Frequently Asked Questions.
 709
 710 @item @rchangesnamed{Top,Changes}:
 711 updates since the last major version.
 712
 713 @item @rextendnamed{Top,Extend}:
 714 programming fancy tweaks in LilyPond.
 715
 716 @item @rinternalsnamed{Top,Internals}:
 717 information about LilyPond's internal structures, which is
 718 required for constructing tweaks.
 719
 720 @end itemize
 721
 722 @divEnd
 723
 724
 725 @divClass{column-center-bottom}
 726 @subheading Downloadable versions
 727
 728 @help{compare tarball vs. zip size, ask about windows users
 729 dealing with tarballs (both gz and bz2), etc.}
 730
 731 @help{on second thought, wait until the new doc build.  write an
 732 apology here for no tarballs}
 733
 734 @divClass{keep-bullets}
 735 @itemize
 736
 737 @item html-split zip
 738
 739 @item html-big zip
 740
 741 @item pdf zip
 742
 743 @item info zip maybe?!?!
 744
 745 @end itemize
 746
 747 @divEnd
 748
 749 @subheading Previous stable versions
 750
 751 @divClass{keep-bullets}
 752 @itemize
 753
 754 @item @uref{http://lilypond.org/doc/v2.12/Documentation/,
 755 LilyPond 2.12 Documentation}
 756
 757 @item @uref{http://lilypond.org/doc/v2.10/Documentation/,
 758 LilyPond 2.10 Documentation}
 759
 760 @item @uref{http://lilypond.org/doc/v2.8/Documentation/,
 761 LilyPond 2.8 Documentation}
 762
 763 @help anybody want to write this stuff?
 764
 765 @end itemize
 766
 767 @divEnd
 768 @divEnd
 769
 770
 771 @node FDL
 772 @unnumberedsec FDL
 773
 774 @divClass{column-center-top}
 775 @subheading Documentation license
 776
 777 The documentation for GNU LilyPond is published under the GNU Free
 778 Documentation License.  An introduction to this license, and our
 779 reasons for choosing it, is given in @ref{Freedom}.
 780
 781 @divEnd
 782
 783 @divClass{column-center-bottom}
 784 @subheading GNU Free Documentation License 1.1
 785
 786 @include fdl.itexi
 787
 788 @divEnd
 789
 790