GDP: NR 2 Reorganisation: correct order of @includes

[lilypond.git] / Documentation / user / introduction.itely

diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely
index 6ace6ebf9079ad0e865b984261e7eb80316a2c1f..5cda80ffeb655ba5f2ab453728cfc4ebec119f02 100644 (file)
--- a/Documentation/user/introduction.itely
+++ b/Documentation/user/introduction.itely
@@ -1,5 +1,5 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @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
 
 @ignore
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 


@@ -7,6 +7,8 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

+@c \version "2.11.38"
+

 @node Introduction
 @chapter Introduction
 
 @node Introduction
 @chapter Introduction
 


@@ -87,9 +89,8 @@ computer edition.
 @end ifnottex
 @end ifnotinfo
 @ifinfo
 @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
 @end ifinfo
 
 @item @tab


@@ -243,7 +244,7 @@ programming language; the program's functionality was set in stone by
 the developers.  That proved to be unsatisfactory for a number of
 reasons:
 
 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
 @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 +541,7 @@ context.  The Score context is the top level notation context.
 
 @seealso
 
 
 @seealso
 

-Program reference: @internalsref{Contexts}.
+Internals Reference: @internalsref{Contexts}.

 
 @lilypond[quote,ragged-right]
 \include "engraver-example.ily"
 
 @lilypond[quote,ragged-right]
 \include "engraver-example.ily"


@@ -569,14 +570,18 @@ The syntax is also the user-interface for LilyPond, hence it is easy
 to type
 
 @example
 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)
 
 @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
 @end lilypond
 
 On a microscopic scale, such syntax is easy to use.  On a larger


@@ -651,8 +656,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.
 
 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
 @end lilypond
 
 @noindent


@@ -690,21 +698,20 @@ to mix music and text in documents.
 @node About this manual
 @section About this manual
 
 @node About this manual
 @section About this manual
 

-There are two manuals about LilyPond: the @emph{user manual} (this
-document), and @emph{program usage}.
+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 User manual

 
 

-The manual is divided into three books.
-
-@subsubheading Learning manual
+@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.
 
 
 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 @bullet
+@itemize

 
 @item
 @ifhtml
 
 @item
 @ifhtml


@@ -715,8 +722,8 @@ gives a gentle introduction to typesetting music.  First time
 users should start here.
 
 @item
 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
 you are not certain where to place a command, read this chapter!
 
 @item


@@ -732,47 +739,51 @@ produces.
 @end itemize
 
 
 @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.
 
 
 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
 
 @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
 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
 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
 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
 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
 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
 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
 explains how to create music functions.
 
 @end itemize


@@ -782,55 +793,57 @@ explains how to create music functions.
 
 This book contains useful reference charts.
 
 
 This book contains useful reference charts.
 

-@itemize @bullet
+@itemize

 @item
 @ifhtml
 The
 @end ifhtml
 @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
 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
 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
 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
 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
 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
 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
 
 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.
 
 
 @subheading Program usage
 
 This book explains how to execute the program and how to integrate
 LilyPond notation with other programs.
 

-@itemize @bullet
+@itemize

 
 @item
 @emph{@rprogram{Install}},
 
 @item
 @emph{@rprogram{Install}},


@@ -848,7 +861,7 @@ section explains how to upgrade input files from previous versions of
 LilyPond.
 
 @item
 LilyPond.
 
 @item

-@emph{@rprogram{LilyPond-book}},
+@emph{@rprogram{lilypond-book}},

 explains the details behind creating
 documents with in-line music examples, like this manual.
 
 explains the details behind creating
 documents with in-line music examples, like this manual.
 


@@ -866,7 +879,7 @@ formats to the @code{.ly} format.
 
 There are a number of other places which may be very valuable.
 
 
 There are a number of other places which may be very valuable.
 

-@itemize @bullet
+@itemize

 @cindex idiom
 @cindex jargon
 @cindex terminology
 @cindex idiom
 @cindex jargon
 @cindex terminology


@@ -892,7 +905,7 @@ advisable to consult the glossary.
 @item
 The
 @ifhtml
 @item
 The
 @ifhtml

-@uref{source/input/lsr/collated-files.html,Snippets}
+@uref{source/input/lsr/lilypond-snippets/index.html,Snippets}

 @end ifhtml
 @ifnothtml
 Snippets
 @end ifhtml
 @ifnothtml
 Snippets


@@ -906,10 +919,10 @@ Repository}.  This website also has a searchable LilyPond manual.
 @item
 The
 @iftex
 @item
 The
 @iftex

-Program reference
+Internals Reference

 @end iftex
 @ifnottex
 @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
 @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


@@ -951,7 +964,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
 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},
 typically be found somewhere below
 @file{/usr/@/share/@/doc/@/lilypond/}.  Initialization files, for
 example @file{scm/@/lily@/.scm}, or @file{ly/@/engraver@/-init@/.ly},


@@ -963,7 +976,7 @@ are usually found in the directory @file{/usr/@/share/@/lilypond/}.
 @cindex lilypond-internals
 @cindex internal documentation
 @cindex Scheme
 @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
 @cindex index
 
 Finally, this and all other manuals, are available online both as PDF