From 1fa6dd93997a84978c936ccb9a11fb49cd93fd26 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Tue, 19 Jun 2007 20:46:14 -0700 Subject: [PATCH] Update "about this manual" to avoid regression tests. --- Documentation/user/README.txt | 2 +- Documentation/user/introduction.itely | 183 ++++++++++++++------------ Documentation/user/macros.itexi | 2 +- 3 files changed, 102 insertions(+), 85 deletions(-) diff --git a/Documentation/user/README.txt b/Documentation/user/README.txt index 8297e4b0f9..c0bc00d1e4 100644 --- a/Documentation/user/README.txt +++ b/Documentation/user/README.txt @@ -50,7 +50,7 @@ GENERAL GUIDELINES `invalid' instead. * Avoid long stretches of input code. Noone is going to read them in - print. Instead refer to an example input file (@inputfileref), these + print. Instead refer to an example input file (with @lsr{}); these are clickable in HTML. * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc. diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 554c039e17..87bb1851a3 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -690,7 +690,13 @@ to mix music and text in documents. @node About this manual @section About this manual -The manual is divided into the following chapters: +The manual is divided into four books. + +@subsubheading Learning manual + +This book explains how to begin learning LilyPond, as well as explaining +some key concepts in easy terms. + @itemize @bullet @item @@ -716,6 +722,16 @@ problems. shows how to change the default engraving that LilyPond produces. +@end itemize + +@subsubheading Notation reference + +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 + @item @emph{@ref{Basic notation}}, discusses topics grouped by notation construct. This section gives @@ -751,6 +767,16 @@ paper size or specifying page breaks. @emph{@ref{Interfaces for programmers}}, 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 @@ -768,6 +794,14 @@ 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. + +@itemize @bullet @item @ifhtml The @@ -810,118 +844,100 @@ is a complete index. @end itemize -Once you are an experienced user, you can use the manual as reference: -there is an extensive index@footnote{If you are looking for something, -and you cannot find it in the manual, that is considered a bug. In -that case, please file a bug report.}, but the document is also -available in -@iftex -a big HTML page, -@end iftex -@ifhtml -@uref{source/Documentation/user/lilypond.html, one big page}, -@end ifhtml -which can be searched easily using the search facility of a web -browser. -@cindex search in manual -@cindex using the manual +@subsubheading Other information -@c FIXME: -@c add/integrate glossary, put in list above -If you are not familiar with music notation or music terminology -(especially if you are a non-native English speaker), it is advisable -to consult the glossary as well. -@iftex -The music glossary explains musical terms, and includes translations -to various languages. It is a separate document, available in HTML -and PDF. -@end iftex -@ifnottex -The @ref{Top,Music glossary,,music-glossary}, explains musical terms and -includes translations to various languages. It is also available in -PDF. -@end ifnottex +There are a number of other places which may be very valuable. + +@itemize @bullet @cindex idiom @cindex jargon @cindex terminology @cindex foreign languages @cindex language +@item +@ifnottex +The @ref{Top,Music glossary,,music-glossary}, explains musical terms and +includes translations to various languages. It is also available in +PDF. +@end ifnottex +@iftex +The music glossary explains musical terms, and includes translations +to various languages. It is a separate document, available in HTML +and PDF. +@end iftex +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. +@cindex snippets +@cindex LSR +@item +The +@ifhtml +@uref{source/input/lsr/collated-files.html,Snippets} +@end ifhtml +@ifnothtml +Snippets +@end ifnothtml +are a great collection of short examples which demonstrate tricks, tips, +and special features of LilyPond. Most of these snippets can also be +found in the @uref{http://lsr.dsi.unimi.it/,LilyPond Snippet +Repository}. This website also has a searchable LilyPond manual. -This manual is not complete without a number of other documents. They -are not available in print, but should be included with the -documentation package for your platform -@itemize @bullet @item +The @iftex Program reference @end iftex @ifnottex -@ref{Top,Program reference,,lilypond-internals}. +@ref{Top,Program reference,,lilypond-internals} @end ifnottex - -The program reference 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 used. +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 used. Almost all formatting functionality that is used internally, is -available directly to the user. For example, all 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 manual -has a @b{See also} subsection, which refers to the generated -documentation. In the HTML document, these subsections have clickable -links. +available directly to the user. For example, all 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 manual has a @b{See +also} subsection, which refers to the generated documentation. In the +HTML document, these subsections have clickable links. -@cindex snippets -@item -@ifnothtml -Various input examples. -@end ifnothtml -@ifhtml -@c Works, but link name is not so nice; so write-out macro -@c @inputfileref{input/test,Various input examples}. -@uref{source/input/test/collated-files.html,Various input examples}. -@end ifhtml +@end itemize -This collection of files shows various tips and tricks, and is -available as a big HTML document, with pictures and explanatory texts -included. -@item -@ifnothtml -The regression tests. -@end ifnothtml +Once you are an experienced user, you can use the manual as reference: +there is an extensive index@footnote{If you are looking for something, +and you cannot find it in the manual, that is considered a bug. In +that case, please file a bug report.}, but the document is also +available in +@iftex +a big HTML page, +@end iftex @ifhtml -@c Works, but link name is not so nice; so write-out macro -@c @inputfileref{input/regression,The regression tests}. -@uref{source/input/regression/collated-files.html,The regression tests}. +@uref{source/Documentation/user/lilypond.html, one big page}, @end ifhtml - -This collection of files tests each notation and engraving feature of -LilyPond in one file. The collection is primarily there to help us -debug problems, but it can be instructive to see how we exercise the -program. The format is similar to the tips and tricks document. -@end itemize +which can be searched easily using the search facility of a web +browser. In all HTML documents that have music fragments embedded, the LilyPond input that was used to produce that image can be viewed by clicking the image. -The location of the documentation files that are mentioned here can -vary from system to system. On occasion, this manual refers to +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/@/test/@/bla@/.ly} may refer to the file -@file{lilypond@/2.x.y/@/input/@/test/@/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/}. +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/}. @cindex adjusting output @cindex variables @@ -936,3 +952,4 @@ Finally, this and all other manuals, are available online both as PDF files and HTML from the web site, which can be found at @uref{http://@/www@/.lilypond@/.org/}. + diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi index ddef52ebc3..5b36bd3a50 100644 --- a/Documentation/user/macros.itexi +++ b/Documentation/user/macros.itexi @@ -135,7 +135,7 @@ @end ifclear -@c usage: @inputfileref{input@/regression,FILE@/-NAME.ly} +@c not used anymore @macro inputfileref{DIR,NAME} @uref{source/\DIR\/collated-files.html#\NAME\,@file{\DIR\/\NAME\}}@c @end macro -- 2.39.2