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 2.12.2
  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{Snippets}:
  54 short tricks, tips, and examples.
  55
  56 @item @ref{Usage}:
  57 discusses the actual programs and operating system-specific
  58 issues.
  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{Internals}:
  77 information about LilyPond's internal structures, which is
  78 required for constructing tweaks.
  79
  80 @end itemize
  81
  82 @divEnd
  83
  84
  85 @divClass{column-center-bottom}
  86 @subheading Other material
  87
  88 @itemize
  89
  90 @item @ref{Translated}:
  91 translation status for non-English readers.
  92
  93 @item @ref{All}:
  94 manuals for older versions and downloadable versions.
  95
  96 @item @ref{Development}:
  97 manuals for the unstable version.
  98
  99 @item @ref{FDL}:
 100 these manuals are published under the GNU Free Documentation
 101 License.
 102
 103 @end itemize
 104
 105 @divEnd
 106
 107
 108 @divClass{hide}
 109 @menu
 110 * Learning::             Learning.
 111 * Glossary::              Glossary.
 112 * Essay::                       Essay.
 113 * Notation::          Reference.
 114 * Usage::           Usage.
 115 * Snippets::                Snippets.
 116 * FAQ::                         FAQ.
 117 * Changes::                     NEWS.
 118 * Internals::         Internals.
 119 * Translated::          Translation.
 120 * All::                 All manuals.
 121 * FDL::                     Licence.
 122 @end menu
 123
 124 @divEnd
 125
 126
 127 @c TRANSLATORS: most of the text in this file came from
 128 @c LM 1.1 About the documentation  (before this section was
 129 @c removed in July 2009).
 130
 131 @node Learning
 132 @unnumberedsec Learning
 133
 134 @divClass{column-left-top}
 135 @subheading Learning manual
 136
 137 This book explains how to begin learning LilyPond, as well as
 138 explaining some key concepts in easy terms.  You should read these
 139 chapters in a linear fashion.
 140
 141 There is a paragraph @strong{See also} at the end of each section,
 142 which contains cross-references to other sections: you should not
 143 follow these cross-references at first reading.  When you have
 144 read all of the manual, you may want to read some sections again
 145 and follow those cross-references for more information.
 146 @divEnd
 147
 148 @divClass{column-right-top}
 149 @subheading Read it now
 150
 151 @itemize
 152
 153 @item @rlearningnamed{Top,Learning}:
 154 read this manual in the same format as this one.
 155
 156 @end itemize
 157 @divEnd
 158
 159 @divClass{column-center-bottom}
 160 @subheading Other formats
 161
 162 @divClass{keep-bullets}
 163 @itemize
 164
 165 @item @uref{../learning/index.html, Learning (split HTML)}:
 166 the manual is split between many HTML pages.
 167 @emph{(small download for each page)}
 168
 169 @item @uref{../learning-big-page.html, Learning (big HTML)}:
 170 read this manual as one huge HTML page.
 171 @emph{(large single download, around 10? Mb)}
 172
 173 @item @uref{../learning.pdf, learning.pdf}:
 174 download as a PDF file.
 175 @emph{(large single download, 2.8 Mb)}
 176
 177 @item @uref{FIXME, learning.info}:
 178 GNU info format for documentation.  FIXME, link broken.
 179
 180 @end itemize
 181 @divEnd
 182 @divEnd
 183
 184 @ignore
 185 @itemize
 186
 187 @item
 188 @item
 189 @rlearning{Tutorial}: gives a gentle introduction to typesetting music.
 190 First time users should start here.
 191
 192 @item
 193 @rlearning{Fundamental concepts}: explains some general concepts about
 194 the LilyPond file format.  If you are not certain where to place a
 195 command, read this chapter!
 196
 197 @item
 198 @rlearning{Tweaking output}: shows how to change the default engraving
 199 that LilyPond produces.
 200
 201 @item
 202 @rlearning{Working on LilyPond projects}: discusses practical uses of
 203 LilyPond and how to avoid some common problems.  Read this before
 204 undertaking large projects!
 205
 206 @end itemize
 207
 208 The Learning also contains appendices which are not part of the
 209 recommended linear reading.  They may be useful for later
 210 viewing:
 211
 212 @itemize
 213
 214 @item
 215 @rlearning{Templates}: shows ready-made templates of LilyPond pieces.
 216 Just cut and paste a template into a file, add notes, and you're
 217 done!
 218
 219 @item
 220 @rlearning{Scheme tutorial}: presents a short introduction to Scheme,
 221 the programming language that music functions use.  This is
 222 material for advanced tweaks; many users never touch Scheme at
 223 all.
 224
 225 @end itemize
 226 @end ignore
 227
 228
 229 @node Glossary
 230 @unnumberedsec Glossary
 231
 232 @rglosnamed{Top,Music glossary}
 233 this explains musical terms, and includes translations to various
 234 languages.  If you are not familiar with music notation or music
 235 terminology (especially if you are a non-native English speaker),
 236 it is highly advisable to consult the glossary.
 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 @divEnd
 250
 251 @divClass{column-right-top}
 252 @subheading Read it now
 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 @divEnd
 261
 262 @divClass{column-center-bottom}
 263 @subheading Other formats
 264
 265 @divClass{keep-bullets}
 266 @itemize
 267
 268 @item @uref{../essay/index.html, Essay (split HTML)}:
 269 the manual is split between many HTML pages.
 270 @emph{(small download for each page)}
 271
 272 @item @uref{../essay-big-page.html, Essay (big HTML)}:
 273 read this manual as one huge HTML page.
 274 @emph{(large single download, around FIXME? Mb)}
 275
 276 @item @uref{../essay.pdf, essay.pdf}:
 277 download as a PDF file.
 278 @emph{(large single download, FIXME? Mb)}
 279
 280 @item @uref{FIXME, essay.info}:
 281 GNU info format for documentation.  FIXME, link broken.
 282
 283 @end itemize
 284 @divEnd
 285 @divEnd
 286
 287
 288
 289 @node Notation
 290 @unnumberedsec Notation
 291
 292 This book explains all the LilyPond commands which produce
 293 notation.
 294
 295 @warning{The Notation assumes that the reader knows
 296 basic material covered in the Learning and is familiar with
 297 the English musical terms presented in the Musical Glossary.}
 298
 299 @ignore
 300 @itemize
 301
 302 @item
 303 @ruser{Musical notation}:
 304 discusses topics grouped by notation construct.  This section
 305 gives details about basic notation that will be useful in almost
 306 any notation project.
 307
 308 @item
 309 @ruser{Specialist notation}:
 310 discusses topics grouped by notation construct.  This section
 311 gives details about special notation that will only be useful for
 312 particular instrument (or vocal) groups.
 313
 314 @item
 315 @ruser{General input and output}:
 316 discusses general information about LilyPond input files and
 317 controlling output.
 318
 319 @item
 320 @ruser{Spacing issues}:
 321 discusses issues which affect the global output, such as selecting
 322 paper size or specifying page breaks.
 323
 324 @item
 325 @ruser{Changing defaults}:
 326 explains how to tweak LilyPond to produce exactly the notation you
 327 want.
 328
 329 @item
 330 @ruser{Interfaces for programmers}:
 331 explains how to create music functions with scheme.
 332
 333 @end itemize
 334
 335 The Notation also contains appendices with useful
 336 reference charts.
 337
 338 @itemize
 339
 340 @item
 341 @ruser{Literature list}:
 342 contains a set of useful reference books for those who wish to
 343 know more on notation and engraving.
 344
 345 @item
 346 @ruser{Notation manual tables}:
 347 are a set of tables showing the chord names, MIDI instruments, a
 348 list of color names, and the Feta font.
 349
 350 @item
 351 @ruser{Cheat sheet}:
 352 is a handy reference of the most common LilyPond commands.
 353
 354 @item
 355 @ruser{LilyPond command index}:
 356 an index of all LilyPond @code{\commands}.
 357
 358 @item
 359 @ruser{LilyPond index}:
 360 a complete index.
 361
 362 @end itemize
 363 @end ignore
 364
 365
 366 @node Usage
 367 @unnumberedsec Usage
 368
 369 This book explains how to execute the programs and how to integrate
 370 LilyPond notation with other programs.
 371
 372 @ignore
 373 @itemize
 374
 375 @item
 376 @rprogram{Install}:
 377 explains how to install LilyPond, including compilation if
 378 desired.
 379
 380 @item
 381 @rprogram{Setup}:
 382 describes how to configure your computer for optimum LilyPond
 383 usage, such as using special environments for certain text
 384 editors.
 385
 386 @item
 387 @rprogram{Running LilyPond}:
 388 shows how to run LilyPond and its helper programs.  In addition,
 389 this section explains how to upgrade input files from previous
 390 versions of LilyPond.
 391
 392 @item
 393 @rprogram{LilyPond-book}:
 394 explains the details behind creating documents with in-line music
 395 examples, like this manual.
 396
 397 @item
 398 @rprogram{Converting from other formats}:
 399 explains how to run the conversion programs.  These programs are
 400 supplied with the LilyPond package, and convert a variety of music
 401 formats to the @code{.ly} format.
 402
 403 @end itemize
 404 @end ignore
 405
 406
 407 @node Snippets
 408 @unnumberedsec Snippets
 409
 410 @rlsrnamed{Top,LilyPond Snippets}: this shows a
 411 selected set of LilyPond snippets from the
 412 @uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
 413 (LSR).  All the snippets are in the public domain.
 414
 415 Please note that this document is not an exact subset of LSR.  LSR
 416 is running a stable LilyPond version, so any snippet which
 417 demonstrates new features of a development version must be added
 418 separately.  These are stored in @file{input/new/} in the LilyPond
 419 source tree.
 420
 421 The list of snippets for each subsection of the Notation are
 422 also linked from the @strong{See also} portion.
 423
 424
 425 @node FAQ
 426 @unnumberedsec FAQ
 427
 428 @warning{to be moved into the actual Documentation/ in master)}
 429
 430
 431 @subheading Where are the graphical canvas, menus, and toolbars?
 432
 433 LilyPond requires you to write music as text.  Please read about
 434 our @ref{Text input}.
 435
 436
 437 @subheading There's a lot of documentation!  Do I need to read it?
 438
 439 You need to read the @ref{Learning}.  As for the rest of
 440 documentation, you only need to read the sections which discuss
 441 the notation that you wish to create.
 442
 443
 444 @subheading That's still a lot of reading!  Is it worth it?
 445
 446 Please decide for yourself; the reasons why you might want to use
 447 LilyPond are given in the @ref{Introduction}.
 448
 449
 450 @subheading Something isn't working!  How do I fix it?
 451
 452 This is explained in @@ref@{FIXME LM or AU x.y@}.
 453
 454
 455 @subheading Why do you change the syntax?
 456
 457 This is explained in @@ref@{FIXME AU x.y@}.
 458
 459
 460 @node Changes
 461 @unnumberedsec Changes
 462
 463 previous-named "NEWS" doc.
 464
 465 this is a summary of important changes
 466 and new features in LilyPond since the previous version.
 467
 468
 469
 470 @node Internals
 471 @unnumberedsec Internals
 472
 473 @rinternalsnamed{Top,Internals}: this is a set
 474 of heavily cross linked HTML pages which document the nitty-gritty
 475 details of each and every LilyPond class, object, and function.
 476 It is produced directly from the formatting definitions in the
 477 source code.
 478
 479 Almost all formatting functionality that is used internally is
 480 available directly to the user.  For example, most variables that
 481 control thickness values, distances, etc., can be changed in input
 482 files.  There are a huge number of formatting options, and all of
 483 them are described in this document.  Each section of the Notation
 484 Reference has a @b{See also} subsection, which refers to the
 485 generated documentation.  In the HTML document, these subsections
 486 have clickable links.
 487
 488
 489
 490 @node Translated
 491 @unnumberedsec Translated
 492
 493 blah
 494
 495
 496 @node All
 497 @unnumberedsec All
 498
 499 @divClass{column-left-top}
 500 @subheading Downloadable versions
 501
 502 FIXME: compare tarball vs. zip size, ask about windows users
 503 dealing with tarballs (both gz and bz2), etc.
 504
 505 @divClass{keep-bullets}
 506 @itemize
 507
 508 @item html-split zip
 509
 510 @item html-big zip
 511
 512 @item pdf zip
 513
 514 @item info zip maybe?!?!
 515
 516 @end itemize
 517
 518 @divEnd
 519 @divEnd
 520
 521 @divClass{column-right-top}
 522 @subheading Previous stable versions
 523
 524 @divClass{keep-bullets}
 525 @itemize
 526
 527 @item @uref{http://lilypond.org/doc/v2.12/Documentation/,
 528 LilyPond 2.12 Documentation}
 529
 530 @item @uref{http://lilypond.org/doc/v2.10/Documentation/,
 531 LilyPond 2.10 Documentation}
 532
 533 @item @uref{http://lilypond.org/doc/v2.8/Documentation/,
 534 LilyPond 2.8 Documentation}
 535
 536 @item FIXME etc.
 537
 538 @end itemize
 539
 540 @divEnd
 541 @divEnd
 542
 543
 544 @node FDL
 545 @unnumberedsec FDL
 546
 547 @divClass{column-center-top}
 548 @subheading Documentation license
 549
 550 The documentation for GNU LilyPond is published under the GNU Free
 551 Documentation License.  An introduction to this license, and our
 552 reasons for choosing it, is given in @ref{Freedom}.
 553
 554 @divEnd
 555
 556 @divClass{column-center-bottom}
 557 @subheading GNU Free Documentation License 1.1
 558
 559 @include fdl.itexi
 560
 561 @divEnd
 562
 563