Change Info docs setup and clean up Documentation/user/GNUmakefile

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

diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely
index 87bb1851a3a45b725bf2e63828563472e3ff4bb8..c6761089033ce9623a1d49e7c83cd751a981aa55 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
 


@@ -87,9 +87,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 +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:
 
 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 +539,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 +568,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 +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.
 
 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,14 +696,20 @@ to mix music and text in documents.
 @node About this manual
 @section About this manual
 
 @node About this manual
 @section About this manual
 

-The manual is divided into four books.
+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}.
+

 
 

-@subsubheading Learning manual
+@subheading Learning Manual (LM)

 
 This book explains how to begin learning LilyPond, as well as explaining
 
 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
 
 @item
 @ifhtml


@@ -708,7 +720,7 @@ 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}},
+@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!
 
 explains some general concepts about the lilypond file format.  If
 you are not certain where to place a command, read this chapter!
 


@@ -724,131 +736,147 @@ 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
 
 

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

 @subsubheading Appendices
 
 This book contains useful reference charts.
 
 @subsubheading Appendices
 
 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.
+
+@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.
 
 
 @subsubheading Other information
 
 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


@@ -874,7 +902,7 @@ advisable to consult the glossary.
 @item
 The
 @ifhtml
 @item
 The
 @ifhtml

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

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


@@ -888,10 +916,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


@@ -917,7 +945,7 @@ available in
 a big HTML page,
 @end iftex
 @ifhtml
 a big HTML page,
 @end iftex
 @ifhtml

-@uref{source/Documentation/user/lilypond.html, one big page},
+@uref{source/Documentation/user/lilypond-big-page.html, one big page},

 @end ifhtml
 which can be searched easily using the search facility of a web
 browser.
 @end ifhtml
 which can be searched easily using the search facility of a web
 browser.