Begin reworking `About the documentation'.

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

diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely
index c6761089033ce9623a1d49e7c83cd751a981aa55..c8c04fb7d9d90b85a5bc086db69d4b69ffa2808a 100644 (file)
--- a/Documentation/user/introduction.itely
+++ b/Documentation/user/introduction.itely
@@ -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
@@ -223,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
@@ -361,7 +376,7 @@ music fragment.
 
 
 @node What symbols to engrave?
-@section What symbols to engrave?
+@subsection What symbols to engrave?
 
 @cindex engraving
 @cindex typography
@@ -539,7 +554,7 @@ context.  The Score context is the top level notation context.
 
 @seealso
 
-Internals Reference: @internalsref{Contexts}.
+Internals Reference: @rinternals{Contexts}.
 
 @lilypond[quote,ragged-right]
 \include "engraver-example.ily"
@@ -552,7 +567,7 @@ Internals 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
@@ -647,7 +662,7 @@ 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
@@ -692,9 +707,72 @@ 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
+
+This section explains the different manuals:
+
+@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.
+
+@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
 
-@node About this manual
-@section About this manual
 
 FIXME: needs almost-complete rewrite.  -gp
 
@@ -721,7 +799,7 @@ users should start here.
 
 @item
 @emph{@ref{Fundamental concepts}},
-explains some general concepts about the lilypond file format.  If
+explains some general concepts about the LilyPond file format.  If
 you are not certain where to place a command, read this chapter!
 
 @item
@@ -835,6 +913,7 @@ is a complete index.
 
 @end ignore
 
+
 @subheading Program usage
 
 This book explains how to execute the program and how to integrate
@@ -902,7 +981,7 @@ advisable to consult the glossary.
 @item
 The
 @ifhtml
-@uref{source/input/lsr/snippets/index.html,Snippets}
+@uref{source/input/lsr/lilypond-snippets/index.html,Snippets}
 @end ifhtml
 @ifnothtml
 Snippets
@@ -961,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},
@@ -973,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