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