X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fintroduction.itely;h=c6761089033ce9623a1d49e7c83cd751a981aa55;hb=ece2e45d587f63565e81af44e1937ebe1f5e47a8;hp=554c039e1724082e63484610757220888e15098c;hpb=e3fbf0543b38e5c20155cef9dc48d70e91da45c2;p=lilypond.git diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 554c039e17..c676108903 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 @@ -87,9 +87,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 @@ -243,7 +242,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 @@ -540,7 +539,7 @@ context. The Score context is the top level notation context. @seealso -Program reference: @internalsref{Contexts}. +Internals Reference: @internalsref{Contexts}. @lilypond[quote,ragged-right] \include "engraver-example.ily" @@ -569,14 +568,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 @@ -651,8 +654,11 @@ 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 @@ -690,8 +696,20 @@ to mix music and text in documents. @node About this manual @section About this manual -The manual is divided into the following chapters: -@itemize @bullet +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. It is recommended to read these +chapters in a linear fashion. + +@itemize @item @ifhtml @@ -702,7 +720,7 @@ gives a gentle introduction to typesetting music. First time users should start here. @item -@emph{@ref{Putting it all together}}, +@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! @@ -716,212 +734,238 @@ problems. shows how to change the default engraving that LilyPond produces. +@end itemize + + +@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. + +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. -@item -@emph{@ref{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. +@end itemize -@item -@emph{@ref{LilyPond-book}}, -explains the details behind creating -documents with in-line music examples, like this manual. -@item -@emph{@ref{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. +@subsubheading Appendices +This book contains useful reference charts. + +@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 -Once you are an experienced user, you can use the manual as reference: -there is an extensive index@footnote{If you are looking for something, -and you cannot find it in the manual, that is considered a bug. In -that case, please file a bug report.}, but the document is also -available in -@iftex -a big HTML page, -@end iftex -@ifhtml -@uref{source/Documentation/user/lilypond.html, one big page}, -@end ifhtml -which can be searched easily using the search facility of a web -browser. -@cindex search in manual -@cindex using the manual +@subheading Program usage -@c FIXME: -@c add/integrate glossary, put in list above -If you are not familiar with music notation or music terminology -(especially if you are a non-native English speaker), it is advisable -to consult the glossary as well. -@iftex -The music glossary explains musical terms, and includes translations -to various languages. It is a separate document, available in HTML -and PDF. -@end iftex -@ifnottex -The @ref{Top,Music glossary,,music-glossary}, explains musical terms and -includes translations to various languages. It is also available in -PDF. -@end ifnottex +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 @cindex idiom @cindex jargon @cindex terminology @cindex foreign languages @cindex language +@item +@ifnottex +The @ref{Top,Music glossary,,music-glossary}, explains musical terms and +includes translations to various languages. It is also available in +PDF. +@end ifnottex +@iftex +The music glossary explains musical terms, and includes translations +to various languages. It is a separate document, available in HTML +and PDF. +@end iftex +If you are not familiar with music notation or music terminology +(especially if you are a non-native English speaker), it is highly +advisable to consult the glossary. +@cindex snippets +@cindex LSR +@item +The +@ifhtml +@uref{source/input/lsr/snippets/index.html,Snippets} +@end ifhtml +@ifnothtml +Snippets +@end ifnothtml +are a great collection of short examples which demonstrate tricks, tips, +and special features of LilyPond. Most of these snippets can also be +found in the @uref{http://lsr.dsi.unimi.it/,LilyPond Snippet +Repository}. This website also has a searchable LilyPond manual. -This manual is not complete without a number of other documents. They -are not available in print, but should be included with the -documentation package for your platform -@itemize @bullet @item +The @iftex -Program reference +Internals Reference @end iftex @ifnottex -@ref{Top,Program reference,,lilypond-internals}. +@ref{Top,Internals Reference,,lilypond-internals} @end ifnottex - -The program reference is a set of heavily cross linked HTML pages, -which document the nitty-gritty details of each and every LilyPond -class, object, and function. It is produced directly from the -formatting definitions used. +is a set of heavily cross linked HTML pages, which document the +nitty-gritty details of each and every LilyPond class, object, and +function. It is produced directly from the formatting definitions used. Almost all formatting functionality that is used internally, is -available directly to the user. For example, all variables that -control thickness values, distances, etc., can be changed in input -files. There are a huge number of formatting options, and all of them -are described in this document. Each section of the notation manual -has a @b{See also} subsection, which refers to the generated -documentation. In the HTML document, these subsections have clickable -links. +available directly to the user. For example, all variables that control +thickness values, distances, etc., can be changed in input files. There +are a huge number of formatting options, and all of them are described +in this document. Each section of the notation manual has a @b{See +also} subsection, which refers to the generated documentation. In the +HTML document, these subsections have clickable links. -@cindex snippets -@item -@ifnothtml -Various input examples. -@end ifnothtml -@ifhtml -@c Works, but link name is not so nice; so write-out macro -@c @inputfileref{input/test,Various input examples}. -@uref{source/input/test/collated-files.html,Various input examples}. -@end ifhtml +@end itemize -This collection of files shows various tips and tricks, and is -available as a big HTML document, with pictures and explanatory texts -included. -@item -@ifnothtml -The regression tests. -@end ifnothtml +Once you are an experienced user, you can use the manual as reference: +there is an extensive index@footnote{If you are looking for something, +and you cannot find it in the manual, that is considered a bug. In +that case, please file a bug report.}, but the document is also +available in +@iftex +a big HTML page, +@end iftex @ifhtml -@c Works, but link name is not so nice; so write-out macro -@c @inputfileref{input/regression,The regression tests}. -@uref{source/input/regression/collated-files.html,The regression tests}. +@uref{source/Documentation/user/lilypond-big-page.html, one big page}, @end ifhtml - -This collection of files tests each notation and engraving feature of -LilyPond in one file. The collection is primarily there to help us -debug problems, but it can be instructive to see how we exercise the -program. The format is similar to the tips and tricks document. -@end itemize +which can be searched easily using the search facility of a web +browser. In all HTML documents that have music fragments embedded, the LilyPond input that was used to produce that image can be viewed by clicking the image. -The location of the documentation files that are mentioned here can -vary from system to system. On occasion, this manual refers to +The location of the documentation files that are mentioned here can vary +from system to system. On occasion, this manual refers to 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/@/test/@/bla@/.ly} may refer to the file -@file{lilypond@/2.x.y/@/input/@/test/@/bla@/.ly}. On binary 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}, are usually found in the directory -@file{/usr/@/share/@/lilypond/}. +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 +typically be found somewhere below +@file{/usr/@/share/@/doc/@/lilypond/}. Initialization files, for +example @file{scm/@/lily@/.scm}, or @file{ly/@/engraver@/-init@/.ly}, +are usually found in the directory @file{/usr/@/share/@/lilypond/}. @cindex adjusting output @cindex variables @@ -936,3 +980,4 @@ Finally, this and all other manuals, are available online both as PDF files and HTML from the web site, which can be found at @uref{http://@/www@/.lilypond@/.org/}. +