X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fintroduction.itely;h=c8c04fb7d9d90b85a5bc086db69d4b69ffa2808a;hb=1098f24a2afed8fd777988c366d7c2339ed6f2d8;hp=01cc7e79262cdb65d6c80d7c45ee0e63348150ac;hpb=c69439a2389be2a111c22571081596d2b7341721;p=lilypond.git diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 01cc7e7926..c8c04fb7d9 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -1,5 +1,5 @@ @c -*- coding: utf-8; mode: texinfo; -*- -@c This file is part of lilypond.tely +@c This file is part of lilypond-learning.tely @ignore Translation of GIT committish: FILL-IN-HEAD-COMMITTISH @@ -7,9 +7,25 @@ version that you are working on. See TRANSLATION for details. @end ignore +@c \version "2.11.38" + @node Introduction @chapter Introduction +This chapter introduces readers to LilyPond and the +documentation. + +@menu +* Background:: +* About the documentation:: +@end menu + + +@node Background +@section Background + +This section covers the overall goals and architecture of +LilyPond. @menu * Engraving:: @@ -17,12 +33,11 @@ * What symbols to engrave?:: * Music representation:: * Example applications:: -* About this manual:: @end menu @node Engraving -@section Engraving +@subsection Engraving The art of music typography is called @emph{(plate) engraving}. The term derives from the traditional process of music printing. Just a @@ -87,9 +102,8 @@ computer edition. @end ifnottex @end ifnotinfo @ifinfo -@c workaround for makeinfo-4.6: line breaks and multi-column cookies -@image{henle-flat-bw,,,png} @image{baer-flat-bw,,,png} -@image{lily-flat-bw,,,png} +@image{lilypond/henle-flat-bw,,,png} @image{lilypond/baer-flat-bw,,,png} +@image{lilypond/lily-flat-bw,,,png} @end ifinfo @item @tab @@ -224,7 +238,7 @@ love to play from. @node Automated engraving -@section Automated engraving +@subsection Automated engraving How do we go about implementing typography? If craftsmen need over ten years to become true masters, how could we simple hackers ever @@ -243,7 +257,7 @@ programming language; the program's functionality was set in stone by the developers. That proved to be unsatisfactory for a number of reasons: -@itemize @bullet +@itemize @item When LilyPond makes mistakes, users need to override formatting decisions. Therefore, the user must have access to the formatting engine. Hence, rules and settings cannot @@ -362,7 +376,7 @@ music fragment. @node What symbols to engrave? -@section What symbols to engrave? +@subsection What symbols to engrave? @cindex engraving @cindex typography @@ -540,7 +554,7 @@ context. The Score context is the top level notation context. @seealso -Program reference: @internalsref{Contexts}. +Internals Reference: @rinternals{Contexts}. @lilypond[quote,ragged-right] \include "engraver-example.ily" @@ -553,7 +567,7 @@ Program reference: @internalsref{Contexts}. @end lilypond @node Music representation -@section Music representation +@subsection Music representation Ideally, the input format for any high-level formatting system is an abstract description of the content. In this case, that would be the @@ -569,14 +583,18 @@ The syntax is also the user-interface for LilyPond, hence it is easy to type @example -c'4 d'8 +@{ + c'4 d'8 +@} @end example @noindent a quarter note C1 (middle C) and an eighth note D1 (D above middle C) -@lilypond[quote,fragment] -c'4 d'8 +@lilypond[quote] +{ + c'4 d'8 +} @end lilypond On a microscopic scale, such syntax is easy to use. On a larger @@ -644,15 +662,18 @@ and representation take up less than 10% of the source code. @node Example applications -@section Example applications +@subsection Example applications We have written LilyPond as an experiment of how to condense the art of music engraving into a computer program. Thanks to all that hard work, the program can now be used to perform useful tasks. The simplest application is printing notes. -@lilypond[quote,relative=1,fragment] -\time 2/4 c4 c g'4 g a4 a g2 +@lilypond[quote,relative=1] +{ + \time 2/4 + c4 c g'4 g a4 a g2 +} @end lilypond @noindent @@ -686,18 +707,87 @@ in the resulting PDF or HTML output files. This makes it easy to mix music and text in documents. +@node About the documentation +@section About the documentation -@node About this manual -@section About this manual +This section explains the different manuals: -The manual is divided into four books. +@itemize +@item +Learning Manual (LM): this introduces LilyPond, giving in-depth +explanations of how to create notation. + +@item +Music Glossary (MG): this explains musical terms and gives +translations of terms in other languages. -@subsubheading Learning manual +@item +Notation Reference (NR): this is the @q{main} portion of the +documentation. It provides detailed information about creating +notation. + +@item +Application Usage (AU): this discusses the actual programs and +operation system-specific issues. + +@item +Snippet List (SL): this is a collection of useful snippets from +the +@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}, +a public-domain collection of LilyPond examples. + +@item +Other documentation: there are a few other portions of the +documentation, such as News items and the mailist archives. + +@end itemize + +@menu +* About the Learning Manual (LM):: +* About the Music Glossary (MG):: +* About the Notation Reference (NR):: +* About the Application Usage (AU):: +* About the Snippet List (SL):: +* Other documentation:: +@end menu + +@c zz +@node About the Learning Manual (LM) +@subsection About the Learning Manual (LM) + + +@node About the Music Glossary (MG) +@subsection About the Music Glossary (MG) + +@node About the Notation Reference (NR) +@subsection About the Notation Reference (NR) + +@node About the Application Usage (AU) +@subsection About the Application Usage (AU) + + +@node About the Snippet List (SL) +@subsection About the Snippet List (SL) + + +@node Other documentation +@subsection Other documentation + + +FIXME: needs almost-complete rewrite. -gp + +There are four manuals about LilyPond: the @emph{Learning Manual}, +the @emph{Notation Reference}, the @emph{Application Usage}, and the +@emph{Internals Reference}. + + +@subheading Learning Manual (LM) This book explains how to begin learning LilyPond, as well as explaining -some key concepts in easy terms. +some key concepts in easy terms. It is recommended to read these +chapters in a linear fashion. -@itemize @bullet +@itemize @item @ifhtml @@ -708,8 +798,8 @@ gives a gentle introduction to typesetting music. First time users should start here. @item -@emph{@ref{Putting it all together}}, -explains some general concepts about the lilypond file format. If +@emph{@ref{Fundamental concepts}}, +explains some general concepts about the LilyPond file format. If you are not certain where to place a command, read this chapter! @item @@ -724,131 +814,148 @@ produces. @end itemize -@subsubheading Notation reference + +@subheading Notation Reference (NR) This book explains all the LilyPond commands which produce notation. It assumes that readers are familiar with the concepts in the Learning manual. -@itemize @bullet +All of this needs to be rewritten after GDP, anyway. + +@ignore + +@itemize @item -@emph{@ref{Basic notation}}, +@emph{@r ef{Basic notation}}, discusses topics grouped by notation construct. This section gives details about basic notation that will be useful in almost any notation project. @item -@emph{@ref{Instrument-specific notation}}, +@emph{@r ef{Instrument-specific notation}}, discusses topics grouped by notation construct. This section gives details about special notation that will only be useful for particular instrument (or vocal) groups. @item -@emph{@ref{Advanced notation}}, +@emph{@r ef{Advanced notation}}, discusses topics grouped by notation construct. This section gives details about complicated or unusual notation. @item -@emph{@ref{Changing defaults}}, +@emph{@r ef{Changing defaults}}, explains how to fine tune layout. @item -@emph{@ref{Non-musical notation}}, +@emph{@r ef{Non-musical notation}}, discusses non-musical output such as titles, multiple movements, and how to select which MIDI instruments to use. @item -@emph{@ref{Spacing issues}}, +@emph{@r ef{Spacing issues}}, discusses issues which affect the global output, such as selecting paper size or specifying page breaks. @item -@emph{@ref{Interfaces for programmers}}, +@emph{@r ef{Interfaces for programmers}}, explains how to create music functions. @end itemize -@subsubheading Program usage - -This book explains how to execute the program and how to integrate -LilyPond notation with other programs. - -@itemize @bullet - -@item -@emph{@rprogram{Running LilyPond}}, -shows how to run LilyPond and its helper programs. In addition, this -section explains how to upgrade input files from previous versions of -LilyPond. - -@item -@emph{@rprogram{LilyPond-book}}, -explains the details behind creating -documents with in-line music examples, like this manual. - -@item -@emph{@rprogram{Converting from other formats}}, -explains how to run the conversion programs. These programs are -supplied with the LilyPond package, and convert a variety of music -formats to the @code{.ly} format. - -@end itemize - - @subsubheading Appendices This book contains useful reference charts. -@itemize @bullet +@itemize @item @ifhtml The @end ifhtml -@emph{@ref{Literature list}}, +@emph{@r ef{Literature list}}, contains a set of useful reference books for those who wish to know more on notation and engraving. @item The -@emph{@ref{Scheme tutorial}}, +@emph{@r ef{Scheme tutorial}}, presents a short introduction to Scheme, the programming language that music functions use. @item -@emph{@ref{Notation manual tables}}, +@emph{@r ef{Notation manual tables}}, are a set of tables showing the chord names, MIDI instruments, a list of color names, and the Feta font. @item -@emph{@ref{Templates}}, +@emph{@r ef{Templates}}, of LilyPond pieces. Just cut and paste a template into a file, add notes, and you're done! @item The -@emph{@ref{Cheat sheet}}, +@emph{@r ef{Cheat sheet}}, is a handy reference of the most common LilyPond commands. @item The -@emph{@ref{LilyPond command index}}, +@emph{@r ef{LilyPond command index}}, is an index of all LilyPond @code{\commands}. @item The -@emph{@ref{LilyPond index}}, +@emph{@r ef{LilyPond index}}, is a complete index. @end itemize +@end ignore + + +@subheading Program usage + +This book explains how to execute the program and how to integrate +LilyPond notation with other programs. + +@itemize + +@item +@emph{@rprogram{Install}}, +explains how to install LilyPond (including compilation if desired). + +@item +@emph{@rprogram{Setup}}, +describes how to configure your computer for optimum LilyPond usage, +such as using special environments for certain text editors. + +@item +@emph{@rprogram{Running LilyPond}}, +shows how to run LilyPond and its helper programs. In addition, this +section explains how to upgrade input files from previous versions of +LilyPond. + +@item +@emph{@rprogram{LilyPond-book}}, +explains the details behind creating +documents with in-line music examples, like this manual. + +@item +@emph{@rprogram{Converting from other formats}}, +explains how to run the conversion programs. These programs are +supplied with the LilyPond package, and convert a variety of music +formats to the @code{.ly} format. + +@end itemize + + @subsubheading Other information There are a number of other places which may be very valuable. -@itemize @bullet +@itemize @cindex idiom @cindex jargon @cindex terminology @@ -874,7 +981,7 @@ advisable to consult the glossary. @item The @ifhtml -@uref{source/input/lsr/collated-files.html,Snippets} +@uref{source/input/lsr/lilypond-snippets/index.html,Snippets} @end ifhtml @ifnothtml Snippets @@ -888,10 +995,10 @@ Repository}. This website also has a searchable LilyPond manual. @item The @iftex -Program reference +Internals Reference @end iftex @ifnottex -@ref{Top,Program reference,,lilypond-internals} +@ref{Top,Internals Reference,,lilypond-internals} @end ifnottex is a set of heavily cross linked HTML pages, which document the nitty-gritty details of each and every LilyPond class, object, and @@ -933,7 +1040,7 @@ initialization and example files. Throughout this manual, we refer to input files relative to the top-directory of the source archive. For example, @file{input/@/lsr/@/dirname/@/bla@/.ly} may refer to the file @file{lilypond@/2.x.y/@/input/@/lsr/@/dirname/@/bla@/.ly}. On binary -packages for the Unix platform, the documentation and examples can +packages for the UNIX platform, the documentation and examples can typically be found somewhere below @file{/usr/@/share/@/doc/@/lilypond/}. Initialization files, for example @file{scm/@/lily@/.scm}, or @file{ly/@/engraver@/-init@/.ly}, @@ -945,7 +1052,7 @@ are usually found in the directory @file{/usr/@/share/@/lilypond/}. @cindex lilypond-internals @cindex internal documentation @cindex Scheme -@cindex extending lilypond +@cindex extending LilyPond @cindex index Finally, this and all other manuals, are available online both as PDF