From 1098f24a2afed8fd777988c366d7c2339ed6f2d8 Mon Sep 17 00:00:00 2001
From: Graham Percival <graham@percival-music.ca>
Date: Sat, 10 May 2008 17:40:35 -0700
Subject: [PATCH] Begin reworking `About the documentation'.

---
 Documentation/index.html.in           |  2 +-
 Documentation/user/introduction.itely | 92 ++++++++++++++++++++++++---
 2 files changed, 85 insertions(+), 9 deletions(-)

diff --git a/Documentation/index.html.in b/Documentation/index.html.in
index 82f04b82b9..fd431f3037 100644
--- a/Documentation/index.html.in
+++ b/Documentation/index.html.in
@@ -101,7 +101,7 @@ href="user/lilypond-program/index.html">Application Usage (AU)</a>
 in <a class="title" href="user/lilypond-program.pdf">PDF</a>)
 	    <br>(how to install and run the program)
 
-<li><a class="title" href="../input/lsr/lilypond-snippets/index.html">Snippets</a>
+<li><a class="title"href="../input/lsr/lilypond-snippets/index.html">Snippets List (SL)</a>
 (in <a class="title" href="../input/lsr/lilypond-snippets-big-page.html">one big page</a>,
 in <a class="title" href="user/lilypond-snippets.pdf">PDF</a>)
      <br>(Short tricks, tips, and examples)
diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely
index b6a3320400..c8c04fb7d9 100644
--- a/Documentation/user/introduction.itely
+++ b/Documentation/user/introduction.itely
@@ -12,6 +12,20 @@
 @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::                   
@@ -19,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
@@ -225,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
@@ -363,7 +376,7 @@ music fragment.
 
 
 @node What symbols to engrave?
-@section What symbols to engrave?
+@subsection What symbols to engrave?
 
 @cindex engraving
 @cindex typography
@@ -554,7 +567,7 @@ Internals Reference: @rinternals{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
@@ -649,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
@@ -694,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
 
-- 
2.39.2