@node Introduction
@chapter Introduction
-This chapter introduces readers to LilyPond and the
-documentation.
+This chapter gives a basic introduction to working with LilyPond.
@menu
-* About the documentation::
+* Compiling a file::
+* How to write input files::
+* How to read the manuals::
@end menu
+@node Compiling a file
+@section Compiling a file
+FIXME: insert text
-@node About the documentation
-@section About the documentation
+@menu
+* Entering input::
+* MacOS X::
+* Windows::
+* Command-line::
+@end menu
-This section explains the different portions of the documentation.
+@node Entering input
+@subsection Entering input
+
+@cindex compiling
+@cindex first example
+@cindex example, first
+@cindex case sensitive
+
+@qq{Compiling} is the term used for processing an input file
+in LilyPond format to produce a file which can be printed and
+(optionally) a MIDI file which can be played. LilyPond input
+files are simple text files. The first example
+shows what a simple input file looks like.
+
+To create sheet music, we write an input file that specifies the
+notation. For example, if we write:
+
+@example
+@{
+ c' e' g' e'
+@}
+@end example
+
+@noindent
+the result looks like this:
+
+@c in this case we don't want verbatim
+@lilypond[quote]
+{
+ c' e' g' e'
+}
+@end lilypond
+
+@warning{Notes and lyrics in LilyPond input must always be
+surrounded by @w{@strong{@{ curly braces @}}}. The braces
+should also be surrounded by a space unless they are at the
+beginning or end of a line to avoid ambiguities. The braces may
+be omitted in some examples in this manual, but don't forget them
+in your own music! For more information about the display of
+examples in the manual, see @ref{How to read the manuals}.}
+
+In addition, LilyPond input is @strong{case sensitive}.
+@w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
+produce an error message.
+
+
+@smallspace
+
+@subheading Viewing output
+
+@c TODO: move index entries
+@cindex PDF file
+@cindex viewing music
+@cindex text editors
+@cindex running LilyPond under MacOS X
+@cindex MacOS X, running LilyPond
+@cindex running LilyPond under Windows
+@cindex Windows, running LilyPond
+@cindex running LilyPond under Unix
+@cindex Unix, running LilyPond
+
+Producing output depends on your operating system and the
+program(s) you use.
-@cindex Learning Manual
-@cindex Music Glossary
-@cindex Notation Reference
-@cindex Application Usage
-@cindex Snippet List
-@cindex Internals Reference
+@itemize
-@c leave these lines wrapping around. It's some texinfo 4.12 thing. -gp
-@c This is actually a limitation of texi2html. -jm
-@menu
-* About the Learning Manual:: this manual introduces LilyPond, giving in-depth explanations of how to create notation.
-* About the Music Glossary:: this manual explains musical terms and gives translations of terms in other languages.
-* About the Notation Reference:: this manual is the main portion of the documentation. It provides detailed information about creating notation. This book assumes that the reader knows basic material covered in the Learning Manual and is familiar with the English musical terms presented in the Musical Glossary.
-* About the Application Usage:: this discusses the actual programs and operating system-specific issues.
-* About the Snippet List:: this is a collection of short LilyPond examples.
-* About the Internals Reference:: this document gives reference information about LilyPond's internal structures, which is required for constructing tweaks.
-* Other documentation:: there are a few other portions of the documentation, such as News items and the mailist archives.
-@end menu
+@item
+@ref{MacOS X, @sourceimage{logo-macosx,,,}}
+@ref{MacOS X, MacOS X} (graphical)
+@item
+@ref{Windows, @sourceimage{logo-windows,,,}}
+@ref{Windows, Microsoft Windows} (graphical)
-@node About the Learning Manual
-@unnumberedsubsec About the Learning Manual
+@item
+@ref{Command-line, @sourceimage{logo-linux,,,}
+@sourceimage{logo-freebsd,,,}
+@sourceimage{logo-macosx,,,}
+@sourceimage{logo-windows,,,}
+}
+@ref{Command-line, All operating systems} (command-line)
-@cindex Learning Manual
+@end itemize
-This book explains how to begin learning LilyPond, as well as
-explaining some key concepts in easy terms. You should read these
-chapters in a linear fashion.
+There are several other text editors available with better support
+for LilyPond. For more information, see
+@rgeneral{Alternate input}.
+
+@warning{The first time you ever run LilyPond, it may take a
+minute or two because all of the system fonts have to be analyzed
+first. After this, LilyPond will be much faster!}
-There is a paragraph @strong{See also} at the end of each section,
-which contains cross-references to other sections: you should not
-follow these cross-references at first reading; when you have read all
-of the Learning Manual, you may want to read some sections again and
-follow cross-references for further reading.
-@itemize
+@node MacOS X
+@subsection MacOS X
-@item
-@ref{Introduction}: explains the background and overall goal of
-LilyPond.
+@warning{These instructions assume that you are using the built-in
+LilyPad editor. If you are using any of the programs described in
+@rgeneral{Alternate input}, please consult the documentation for
+those programs if you have any problems compiling a file.}
-@item
-@ref{Tutorial}: gives a gentle introduction to typesetting music.
-First time users should start here.
-@item
-@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!
+If you double click @command{LilyPond.app}, it will open with an
+example file. Save it, for example, to @file{test.ly} on your
+Desktop, and then process it with the menu command
+@w{@code{Compile > Typeset File}}. The resulting PDF file will be
+displayed on your screen.
-@item
-@ref{Tweaking output}: shows how to change the default engraving
-that LilyPond produces.
+For future use of LilyPond, you should begin by selecting @q{New}
+or @q{Open}. You must save your file before typesetting it. If
+any errors occur in processing, please see the log window.
-@item
-@ref{Working on LilyPond projects}: discusses practical uses of
-LilyPond and how to avoid some common problems. Read this before
-undertaking large projects!
+@c FIXME: add screenshots
-@end itemize
+@node Windows
+@subsection Windows
-The Learning Manual also contains appendices which are not part of the
-recommended linear reading. They may be useful for later
-viewing:
+@warning{These instructions assume that you are using the built-in
+LilyPad editor. If you are using any of the programs described in
+@rgeneral{Alternate input}, please consult the documentation for
+those programs if you have any problems compiling a file.}
-@itemize
+On Windows, if you double-click in the LilyPond icon on the
+Desktop, it will open a simple text editor with an example file.
+Save it, for example, to @file{test.ly} on your Desktop and then
+double-click on the file to process it (the file icon looks like a
+note). After some seconds, you will get a file @file{test.pdf} on
+your desktop. Double-click on this PDF file to view the typeset
+score. An alternative method to process the @file{test.ly} file
+is to drag and drop it onto the LilyPond icon using your mouse
+pointer.
-@item
-@ref{Templates}: shows ready-made templates of LilyPond pieces.
-Just cut and paste a template into a file, add notes, and you're
-done!
+To edit an existing @file{.ly} file, right-click on it and
+select @qq{Edit source}. To get an empty file to start from, run
+the editor as described above and use @qq{New} in
+the @qq{File} menu, or right-click on the desktop and select
+@qq{New..Text Document}, change its name to a name of your choice
+and change the file extension to @code{.ly}. Double-click the
+icon to type in your LilyPond source code as before.
-@item
-@ref{Scheme tutorial}: presents a short introduction to Scheme,
-the programming language that music functions use. This is
-material for advanced tweaks; many users never touch Scheme at
-all.
+Double-clicking the file does not only result in a PDF file, but
+also produces a @file{.log} file that contains some information on
+what LilyPond has done to the file. If any errors occur, please
+examine this file.
-@end itemize
+@c FIXME: add screenshots
-@node About the Music Glossary
-@unnumberedsubsec About the Music Glossary
+@node Command-line
+@subsection Command-line
-@cindex Music Glossary
-@cindex idiom
-@cindex jargon
-@cindex terminology
-@cindex foreign languages
-@cindex language
+@warning{These instructions assume that you are using commond unix
+command-line programs. If you are using any of the programs
+described in @rgeneral{Alternate input}, please consult the
+documentation for those programs if you have any problems
+compiling a file.}
-@rglosnamed{Top,Music glossary}
-this explains musical terms, and includes translations to various
-languages. 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.
+Create a text file called @file{test.ly} and enter:
-@node About the Notation Reference
-@unnumberedsubsec About the Notation Reference
+@example
+@{
+ c' e' g' e'
+@}
+@end example
-@cindex Notation Reference
-@cindex appendices
-@cindex reference charts
-@cindex charts, reference
+To process @file{test.ly}, proceed as follows:
-This book explains all the LilyPond commands which produce
-notation. It assumes that readers are familiar with the concepts
-in the Learning Manual.
+@example
+lilypond test.ly
+@end example
-@itemize
+@noindent
+You will see something resembling:
-@item
-@ruser{Musical notation}:
-discusses topics grouped by notation construct. This section
-gives details about basic notation that will be useful in almost
-any notation project.
+@example
+lilypond test.ly
+GNU LilyPond @version{}
+Processing `test.ly'
+Parsing...
+Interpreting music...
+Preprocessing graphical objects...
+Finding the ideal number of pages...
+Fitting music on 1 page...
+Drawing systems...
+Layout output to `test.ps'...
+Converting to `test.pdf'...
+@end example
-@item
-@ruser{Specialist 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.
+You may view or print the resulting @file{text.pdf}.
-@item
-@ruser{General input and output}:
-discusses general information about LilyPond input files and
-controlling output.
-@item
-@ruser{Spacing issues}:
-discusses issues which affect the global output, such as selecting
-paper size or specifying page breaks.
+@node How to write input files
+@section How to write input files
-@item
-@ruser{Changing defaults}:
-explains how to tweak LilyPond to produce exactly the notation you
-want.
+FIXME: insert text
-@item
-@ruser{Interfaces for programmers}:
-explains how to create music functions with scheme.
+@menu
+* Simple notation::
+* Working on input files::
+@end menu
-@end itemize
-The Notation Reference also contains appendices with useful
-reference charts.
+@node Simple notation
+@subsection Simple notation
+
+@cindex simple notation
+@cindex notation, simple
+
+LilyPond will add some notation elements automatically. In the
+next example, we have only specified four pitches, but LilyPond
+has added a clef, time signature, and rhythms.
+
+@lilypond[verbatim,quote]
+{
+ c' e' g' e'
+}
+@end lilypond
+
+@noindent
+This behavior may be altered, but in most cases these automatic
+values are useful.
+
+
+@subheading Pitches
+
+@cindex pitches
+@cindex relative mode
+@cindex quote, single
+@cindex comma
+@cindex accidentals and relative mode
+@cindex relative mode, and accidentals
+
+@funindex \relative
+@funindex relative
+@funindex '
+@funindex ,
+
+Music Glossary: @rglos{pitch}, @rglos{interval},
+@rglos{scale}, @rglos{middle C}, @rglos{octave},
+@rglos{accidental}.
+
+The easiest way to enter notes is by using @code{\relative} mode.
+In this mode, the octave is chosen automatically by assuming the
+following note is always to be placed closest to the previous
+note, i.e., it is to be placed in the octave which is within three
+staff spaces of the previous note. We begin by entering the most
+elementary piece of music, a @notation{scale}, in which every note
+is within just one staff space of the previous note.
+
+@lilypond[verbatim,quote]
+% set the starting point to middle C
+\relative c' {
+ c d e f
+ g a b c
+}
+@end lilypond
+
+The initial note is @notation{middle C}. Each successive note is
+placed closest to the previous note -- in other words, the first
+@code{c} is the closest C to middle C. This is followed by the
+closest D to the previous note. We can create melodies which have
+larger intervals, still using only @code{\relative} mode:
+
+@lilypond[verbatim,quote]
+\relative c' {
+ d f a g
+ c b f d
+}
+@end lilypond
+
+@noindent
+It is not necessary for the first note of the melody to start on
+the note which specifies the starting pitch. In the previous
+example, the first note -- the @code{d} -- is the closest D to
+middle C.
+
+By adding (or removing) quotes @code{'} or commas @code{,} from
+the @code{@w{\relative c' @{}} command, we can change the starting
+octave:
+
+@lilypond[verbatim,quote]
+% one octave above middle C
+\relative c'' {
+ e c a c
+}
+@end lilypond
+
+Relative mode can be confusing initially, but is the easiest way
+to enter most melodies. Let us see how this relative calculation
+works in practice. Starting from a B, which is on the middle line
+in a treble clef, you can reach a C, D and E within 3 staff spaces
+going up, and an A, G and F within 3 staff spaces going down. So
+if the note following a B is a C, D or E it will be assumed to be
+above the B, and an A, G or F will be assumed to be below.
+
+@lilypond[verbatim,quote]
+\relative c'' {
+ b c % c is 1 staff space up, so is the c above
+ b d % d is 2 up or 5 down, so is the d above
+ b e % e is 3 up or 4 down, so is the e above
+ b a % a is 6 up or 1 down, so is the a below
+ b g % g is 5 up or 2 down, so is the g below
+ b f % f is 4 up or 3 down, so is the f below
+}
+@end lilypond
+
+Exactly the same happens even when any of these notes are
+sharpened or flattened. @notation{Accidentals} are
+@strong{totally ignored} in the calculation of relative position.
+Precisely the same staff space counting is done from a note at any
+other position on the staff.
+
+To add intervals that are larger than three staff spaces, we can
+raise the @notation{octave} by adding a single quote @code{'} (or
+apostrophe) to the note name. We can lower the octave by adding a
+comma @code{,} to the note name.
+
+@lilypond[verbatim,quote]
+\relative c'' {
+ a a, c' f,
+ g g'' a,, f'
+}
+@end lilypond
+
+@noindent
+To change a note by two (or more!) octaves, we use multiple
+@code{''} or @code{,,} -- but be careful that you use two single
+quotes @code{''} and not one double quote @code{"}@tie{}! The
+initial value in @code{@w{\relative c'}} may also be modified like
+this.
+@c " - keeps quotes in order for context-sensitive editor -td
+
+@subheading Durations (rhythms)
+
+@cindex note durations
+@cindex durations
+@cindex rhythms
+@cindex whole note
+@cindex half note
+@cindex quarter note
+@cindex dotted note
+@cindex notating durations
+
+Music Glossary: @rglos{beam}, @rglos{duration},
+@rglos{whole note}, @rglos{half note}, @rglos{quarter note},
+@rglos{dotted note}.
+
+The @notation{duration} of a note is specified by a number after
+the note name: @code{1} for a @notation{whole note}, @code{2} for
+a @notation{half note}, @code{4} for a @notation{quarter note} and
+so on. @notation{Beams} are added automatically.
+
+If you do not specify a duration, the previous duration is used
+for the next note. The duration of the first note defaults to a
+quarter.
+
+@lilypond[verbatim,quote]
+\relative c'' {
+ a1
+ a2 a4 a8 a
+ a16 a a a a32 a a a a64 a a a a a a a a2
+}
+@end lilypond
+
+To create @notation{dotted notes}, add a dot @code{.} to the
+duration number. The duration of a dotted note must be stated
+explicitly (i.e., with a number).
+
+@lilypond[verbatim,quote]
+\relative c'' {
+ a a a4. a8
+ a8. a16 a a8. a8 a4.
+}
+@end lilypond
+
+
+@subheading Rests
+
+@cindex rest
+@cindex notating rests
+
+Music Glossary: @rglos{rest}.
+
+A @notation{rest} is entered just like a note with the name
+@code{r}@tie{}:
+
+@lilypond[verbatim,quote]
+\relative c'' {
+ a r r2
+ r8 a r4 r4. r8
+}
+@end lilypond
+
+
+@subheading Time signature
+
+@cindex time signature
+
+@funindex \time
+@funindex time
+
+Music Glossary: @rglos{time signature}.
+
+The @notation{time signature} can be set with the @code{\time}
+command:
+
+@lilypond[verbatim,quote]
+\relative c'' {
+ \time 3/4
+ a4 a a
+ \time 6/8
+ a4. a
+ \time 4/4
+ a4 a a a
+}
+@end lilypond
+
+
+@subheading Clef
+
+@cindex clef
+@cindex treble
+@cindex alto
+@cindex tenor
+@cindex bass
+
+@funindex \clef
+@funindex clef
-@itemize
+Music Glossary: @rglos{clef}.
-@item
-@ruser{Literature list}:
-contains a set of useful reference books for those who wish to
-know more on notation and engraving.
+The @notation{clef} can be set using the @code{\clef} command:
-@item
-@ruser{Notation manual tables}:
-are a set of tables showing the chord names, MIDI instruments, a
-list of color names, and the Feta font.
+@lilypond[verbatim,quote]
+\relative c' {
+ \clef treble
+ c1
+ \clef alto
+ c1
+ \clef tenor
+ c1
+ \clef bass
+ c1
+}
+@end lilypond
-@item
-@ruser{Cheat sheet}:
-is a handy reference of the most common LilyPond commands.
-@item
-@ruser{LilyPond command index}:
-an index of all LilyPond @code{\commands}.
+@subheading All together
-@item
-@ruser{LilyPond index}:
-a complete index.
+Here is a small example showing all these elements together:
-@end itemize
+@lilypond[verbatim,quote]
+\relative c, {
+ \time 3/4
+ \clef bass
+ c2 e8 c' g'2.
+ f4 e d c4 c, r4
+}
+@end lilypond
-@node About the Application Usage
-@unnumberedsubsec About the Application Usage
+@seealso
+Notation Reference: @ruser{Writing pitches},
+@ruser{Writing rhythms}, @ruser{Writing rests},
+@ruser{Time signature}, @ruser{Clef}.
-@cindex Application Usage
-@cindex integrating LilyPond with other programs
-This book explains how to execute the programs and how to integrate
-LilyPond notation with other programs.
+@node Working on input files
+@subsection Working on input files
-@itemize
+@cindex curly braces
+@cindex braces, curly
+@cindex comments
+@cindex line comment
+@cindex comment, line
+@cindex block comment
+@cindex comment, line
+@cindex case sensitive
+@cindex whitespace insensitive
+@cindex expressions
-@item
-@rprogram{Install}:
-explains how to install LilyPond, including compilation if
-desired.
+@funindex { ... }
+@funindex %
+@funindex %@{ ... %@}
-@item
-@rprogram{Setup}:
-describes how to configure your computer for optimum LilyPond
-usage, such as using special environments for certain text
-editors.
+LilyPond input files are similar to source files in many common
+programming languages. They are case sensitive, and white-space
+is generally ignored. Expressions are formed with curly braces
+@{ @}, and comments are denoted with @code{%} or
+@w{@code{%@{ ... %@}}}.
+
+If the previous sentences sound like nonsense, don't worry! We'll
+explain what all these terms mean:
+
+@itemize
@item
-@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.
+@strong{Case sensitive}:
+it matters whether you enter a letter in lower case (e.g.
+@w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
+Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
+@w{@code{@{ C D E @}}} will produce an error message.
@item
-@rprogram{LilyPond-book}:
-explains the details behind creating documents with in-line music
-examples, like this manual.
+@strong{Whitespace insensitive}:
+it does not matter how many spaces (or tabs or new lines) you add.
+@w{@code{@{ c d e @}}} means the same thing as
+@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
+
+@example
+@{ c d
+ e @}
+@end example
+
+@noindent
+Of course, the previous example is hard to read. A good rule of
+thumb is to indent code blocks with either a tab or two spaces:
+
+@example
+@{
+ c d e
+@}
+@end example
+
+However, whitespace @emph{is} required to separate many syntactical
+elements from others. In other words, whitespace can always be
+@emph{added}, but it cannot be @emph{eliminated}. As missing
+whitespace can give rise to strange errors it is advisable to
+always insert whitespace before and after every syntactic element,
+for example, before and after every curly brace.
@item
-@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.
+@strong{Expressions}:
+every piece of LilyPond input needs to have @strong{@{ curly
+braces @}} placed around the input. These braces tell LilyPond
+that the input is a single music expression, just like parentheses
+@code{()} in mathematics. The braces should be surrounded by a
+space unless they are at the beginning or end of a line to avoid
+ambiguities.
+
+A LilyPond command followed by a simple expression in braces (such
+as @w{@code{\relative @{ @}}}) also counts as a single music
+expression.
+
+@cindex comments
+@cindex line comment
+@cindex block comment
+@item
+@strong{Comments}:
+a comment is a remark for the human reader of the music input; it
+is ignored while parsing, so it has no effect on the printed
+output. There are two types of comments. The percent symbol
+@code{%} introduces a line comment; anything after @code{%} on
+that line is ignored. By convention, a line comment is placed
+@emph{above} the code it refers to.
+
+@example
+a4 a a a
+% this comment refers to the Bs
+b2 b
+@end example
+
+A block comment marks a whole section of music input as a comment.
+Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
+However, block comments do not @q{nest}. This means that you
+cannot place a block comment inside another block comment. If you
+try, the first @code{%@}} will terminate @emph{both} block
+comments. The following fragment shows possible uses for
+comments:
+
+@example
+% notes for twinkle twinkle follow
+ c4 c g' g a a g2
+
+%@{
+ This line, and the notes below are ignored,
+ since they are in a block comment.
+
+ f f e e d d c2
+%@}
+@end example
@end itemize
-@node About the Snippet List
-@unnumberedsubsec About the Snippet List
+@node How to read the manuals
+@section How to read the manuals
+
+FIXME: fluff here
+
+@menu
+* Omitting braces::
+* Clickable examples::
+* Keyboard navigation::
+* Overview of manuals::
+@end menu
+
+
+@node Omitting braces
+@subsection Omitting braces
-@cindex snippets
-@cindex LSR
-@cindex Snippet List
-@cindex LilyPond Snippet Repository
-@rlsrnamed{Top,LilyPond Snippet List}: this shows a
-selected set of LilyPond snippets from the
-@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
-(LSR). All the snippets are in the public domain.
+@cindex how to read the manual
+@cindex manual, reading
+@cindex reading the manual
+@cindex examples, clickable
+@cindex clickable examples
+@cindex tips for constructing files
+@cindex templates
+@cindex constructing files, tips
+@cindex files, tips for constructing
-Please note that this document is not an exact subset of LSR. LSR
-is running a stable LilyPond version, so any snippet which
-demonstrates new features of a development version must be added
-separately. These are stored in @file{input/new/} in the LilyPond
-source tree.
+LilyPond input must be surrounded by @{ @} marks or a
+@code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
+input files}. For the rest of this manual, most examples will
+omit this. To replicate the examples, you may copy and paste the
+displayed input, but you @strong{must} add the
+@code{@w{\relative c'' @{ @}}} like this:
-The list of snippets for each subsection of the Notation Reference are
-also linked from the @strong{See also} portion.
+@example
+\relative c'' @{
+ ... example goes here...
+@}
+@end example
+Why omit the braces? Most examples in this manual can be inserted
+into the middle of a longer piece of music. For these examples,
+it does not make sense to add @code{@w{\relative c'' @{ @}}} --
+you should not place a @code{\relative} inside another
+@code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
+around every example, you would not be able to copy a small
+documentation example and paste it inside a longer piece of your
+own. Most people want to add material to an existing piece, so we
+format the manual this way.
-@node About the Internals Reference
-@unnumberedsubsec About the Internals Reference
-@cindex Internals Reference
+@node Clickable examples
+@subsection Clickable examples
-@rinternalsnamed{Top,Internals Reference}: this 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 in the
-source code.
+@warning{This features is only available in the HTML manuals.}
-Almost all formatting functionality that is used internally is
-available directly to the user. For example, most 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
-Reference has a @b{See also} subsection, which refers to the
-generated documentation. In the HTML document, these subsections
-have clickable links.
+Many people learn programs by trying and fiddling around with the
+program. This is also possible with LilyPond. If you click on a
+picture in the HTML version of this manual, you will see the exact
+LilyPond input that was used to generate that image. Try it on
+this image:
+@c no verbatim here
+@lilypond[quote]
+\relative c'' {
+ c-\markup { \bold \huge { Click here. } }
+}
+@end lilypond
-@node Other documentation
-@unnumberedsubsec Other documentation
+By cutting and pasting everything in the @qq{ly snippet} section,
+you have a starting template for experiments. To see exactly the
+same output (line-width and all), copy everything from @qq{Start
+cut-&-pastable section} to the bottom of the file.
-There are a number of other sources of information which may be
-very valuable.
+
+@node Keyboard navigation
+@subsection Keyboard navigation
+
+@warning{This features is only available in the HTML manuals.}
+
+@c TODO: once this is figured out, insert it here.
+
+We are currently working on this feature.
+
+
+@node Overview of manuals
+@subsection Overview of manuals
+
+There is a lot of documentation for LilyPond. New users are
+sometimes confused about what part(s) they should read, and
+occasionally skip over reading vital portions.
+
+@warning{Please do not skip over important parts of the
+documentation. You will find it much harder to understand later
+sections.}
@itemize
@item
-@ifhtml
-@ifset bigpage
-@uref{../topdocs/NEWS.html,News}:
-@end ifset
-@ifclear bigpage
-@uref{../../topdocs/NEWS.html,News}:
-@end ifclear
-@end ifhtml
-@ifnothtml
-News:
-@end ifnothtml
-this is a summary of important changes
-and new features in LilyPond since the previous version.
-
-@item @uref{http://lists.gnu.org/archive/html/lilypond-user/, The
-lilypond-user mailist archives}: this is a collection of previous
-emails sent to the user list. Many questions have been asked
-multiple times; there is a very good chance that if you have a
-question, the answer might be found in these archives.
-
-@item @uref{http://lists.gnu.org/archive/html/lilypond-devel/, The
-lilypond-devel mailist archives}: this is a collection of previous
-emails sent to the developer's list. The discussion here is more
-technical; if you have an advanced question about lilypond
-internals, the answer might be in these archives.
-
-@item Embedded music fragments: in all HTML documents that have
-music fragments embedded, the exact LilyPond input that was used
-to produce that image can be viewed by clicking the image.
-
-@item Init files: 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/@/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/}.
-For more details, see @ref{Other sources of information}.
+@strong{Before trying to do @emph{anything}}: read the Learning
+manual's @ref{Introduction}, and @ref{Common notation}. If you
+encounter musical terms which you do not recognize, please look
+them up in the @rglosnamed{Top, Glossary}.
+
+@item
+@strong{Before trying to write a complete piece of music}: read
+the Learning manual's @ref{Fundamental concepts}. After that, you
+may want to look in relevant sections of the
+@rusernamed{Top, Notation reference}.
+
+@item
+@strong{Before trying to change the default output}: read the
+Learning manual's @ref{Tweaking output}.
+
+@item
+@strong{Before undertaking a large project}: read Usage document's
+@rprogram{Suggestions for writing files}.
@end itemize
+
+
projects / lilypond.git / blobdiff