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