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