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