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 @item @uref{changes/index.html, Changes (split HTML)}:
 506 the manual is split between many HTML pages.
 507 @emph{(small download for each page)}
 508
 509 @item @uref{changes-big-page.html, Changes (big HTML)}:
 510 read this manual as one huge HTML page.
 511 @emph{(large single download, around 10? Mb)}
 512
 513 @item @uref{changes.pdf, changes.pdf}:
 514 download as a PDF file.
 515 @emph{(small single download, 0.5 ?? Mb)}
 516
 517 @c @item @uref{TODO, changes.info}:
 518 @c GNU info format for documentation.  TODO, link broken.
 519
 520 @end itemize
 521 @divEnd
 522 @divEnd
 523
 524
 525 @node Extend
 526 @unnumberedsec Extend
 527
 528 @divClass{column-left-top}
 529 @subheading Extend LilyPond
 530
 531 This manual explains how to write extensions to LilyPond.
 532
 533 @divEnd
 534
 535 @divClass{column-right-bottom}
 536 @subheading Read it
 537
 538 @itemize
 539
 540 @item @rextendnamed{Top,Extend}:
 541 read this manual in the same format as this one.
 542
 543 @end itemize
 544
 545 @subheading All formats
 546
 547 @divClass{keep-bullets}
 548 @itemize
 549
 550 @item @uref{extending/index.html, Extend (split HTML)}:
 551 the manual is split between many HTML pages.
 552 @emph{(small download for each page)}
 553
 554 @item @uref{extending-big-page.html, Extend (big HTML)}:
 555 read this manual as one huge HTML page.
 556 @emph{(large single download, around 10? Mb)}
 557
 558 @item @uref{extending.pdf, extending.pdf}:
 559 download as a PDF file.
 560 @emph{(large single download, 2.8 Mb)}
 561
 562 @c @item @uref{TODO, extending.info}:
 563 @c GNU info format for documentation.  TODO, link broken.
 564
 565 @end itemize
 566 @divEnd
 567 @divEnd
 568
 569
 570 @node Internals
 571 @unnumberedsec Internals
 572
 573 @divClass{column-left-top}
 574 @subheading Internals reference
 575
 576 This is a set of heavily cross linked HTML pages which document
 577 the nitty-gritty details of each and every LilyPond class, object,
 578 and function.  It is produced directly from the formatting
 579 definitions in the source code.
 580
 581 Almost all formatting functionality that is used internally is
 582 available directly to the user.  For example, most variables that
 583 control thickness values, distances, etc., can be changed in input
 584 files.  There are a huge number of formatting options, and all of
 585 them are described in this document.  Each section of the Notation
 586 Reference has a @b{See also} subsection, which refers to the
 587 generated documentation.  In the HTML document, these subsections
 588 have clickable links.
 589
 590 @divEnd
 591
 592 @divClass{column-right-bottom}
 593 @subheading Read it
 594
 595 @itemize
 596
 597 @item @rinternalsnamed{Top,Internals}:
 598 read this manual in the same format as this one.
 599
 600 @end itemize
 601
 602 @subheading All formats
 603
 604 @divClass{keep-bullets}
 605 @itemize
 606
 607 @item @uref{internals/index.html, Internals (split HTML)}:
 608 the manual is split between many HTML pages.
 609 @emph{(small download for each page)}
 610
 611 @item @uref{internals-big-page.html, Internals (big HTML)}:
 612 read this manual as one huge HTML page.
 613 @emph{(large single download, around 10? Mb)}
 614
 615 @item @uref{internals.pdf, internals.pdf}:
 616 download as a PDF file.
 617 @emph{(large single download, 2.8 Mb)}
 618
 619 @c @item @uref{TODO, internals.info}:
 620 @c GNU info format for documentation.  TODO, link broken.
 621
 622 @end itemize
 623 @divEnd
 624 @divEnd
 625
 626
 627
 628 @node Translated
 629 @unnumberedsec Translated
 630
 631 @divClass{column-center-bottom}
 632 @subheading Translation status
 633
 634 TODO: clean up / prettify
 635
 636 @uref{translations.html}.
 637
 638 @divEnd
 639
 640
 641 @node All
 642 @unnumberedsec All
 643
 644 @divClass{column-left-top}
 645 @subheading Downloadable versions
 646
 647 @help{compare tarball vs. zip size, ask about windows users
 648 dealing with tarballs (both gz and bz2), etc.}
 649
 650 @help{on second thought, wait until the new doc build.  write an
 651 apology here for no tarballs}
 652
 653 @divClass{keep-bullets}
 654 @itemize
 655
 656 @item html-split zip
 657
 658 @item html-big zip
 659
 660 @item pdf zip
 661
 662 @item info zip maybe?!?!
 663
 664 @end itemize
 665
 666 @divEnd
 667 @divEnd
 668
 669 @divClass{column-right-top}
 670 @subheading Previous stable versions
 671
 672 @divClass{keep-bullets}
 673 @itemize
 674
 675 @item @uref{http://lilypond.org/doc/v2.12/Documentation/,
 676 LilyPond 2.12 Documentation}
 677
 678 @item @uref{http://lilypond.org/doc/v2.10/Documentation/,
 679 LilyPond 2.10 Documentation}
 680
 681 @item @uref{http://lilypond.org/doc/v2.8/Documentation/,
 682 LilyPond 2.8 Documentation}
 683
 684 @help anybody want to write this stuff?
 685
 686 @end itemize
 687
 688 @divEnd
 689 @divEnd
 690
 691
 692 @node FDL
 693 @unnumberedsec FDL
 694
 695 @divClass{column-center-top}
 696 @subheading Documentation license
 697
 698 The documentation for GNU LilyPond is published under the GNU Free
 699 Documentation License.  An introduction to this license, and our
 700 reasons for choosing it, is given in @ref{Freedom}.
 701
 702 @divEnd
 703
 704 @divClass{column-center-bottom}
 705 @subheading GNU Free Documentation License 1.1
 706
 707 @include fdl.itexi
 708
 709 @divEnd
 710
 711