From fea9aa8c14846a1a39a6780434cb386f3b761b54 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Sat, 10 May 2008 22:03:36 -0700 Subject: [PATCH] More `about' stuff, plus THANKS and TODO lists. --- Documentation/user/introduction.itely | 257 +++++++++++--------------- Documentation/user/rhythms.itely | 27 +++ Documentation/user/spacing.itely | 41 +++- THANKS | 2 + 4 files changed, 180 insertions(+), 147 deletions(-) diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 079e387693..a079f30e27 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -37,7 +37,7 @@ LilyPond. @node Engraving -@subsection Engraving +@unnumberedsubsec Engraving The art of music typography is called @emph{(plate) engraving}. The term derives from the traditional process of music printing. Just a @@ -238,7 +238,7 @@ love to play from. @node Automated engraving -@subsection Automated engraving +@unnumberedsubsec 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 @@ -376,7 +376,7 @@ music fragment. @node What symbols to engrave? -@subsection What symbols to engrave? +@unnumberedsubsec What symbols to engrave? @cindex engraving @cindex typography @@ -567,7 +567,7 @@ Internals Reference: @rinternals{Contexts}. @end lilypond @node Music representation -@subsection Music representation +@unnumberedsubsec 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 @@ -662,7 +662,7 @@ and representation take up less than 10% of the source code. @node Example applications -@subsection Example applications +@unnumberedsubsec 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 @@ -710,6 +710,8 @@ to mix music and text in documents. @node About the documentation @section About the documentation +FIXME: still needs some work. + This section explains the different manuals: @itemize @@ -722,9 +724,11 @@ 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 +Notation Reference (NR): this is the main portion of the documentation. It provides detailed information about creating -notation. +notation. This book assumes that the reader knows basic material +covered in the LM and is familiar with the English musical terms +presented in the MG. @item Application Usage (AU): this discusses the actual programs and @@ -734,6 +738,11 @@ operation system-specific issues. Snippet List (SL): this is a collection of short LilyPond examples (@qq{snippets}). +@item +Internals Reference (IR): this gives information about LilyPond +internal programming information, which is required for +constructing tweaks. + @item Other documentation: there are a few other portions of the documentation, such as News items and the mailist archives. @@ -746,186 +755,138 @@ documentation, such as News items and the mailist archives. * About the Notation Reference (NR):: * About the Application Usage (AU):: * About the Snippet List (SL):: +* About the Internals Reference (IR):: * 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) - -The Snippet List shows a selected set of LilyPond snippets from the -@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository} -(LSR). It is in the public domain. - -Please note that this document is not an exact subset of LSR. LSR -is running a stable LilyPond version, so any snippet which -demonstrates new features of a development version must be added -separately. These are stored in @file{input/new/} in the LilyPond -source tree. - -The list of snippets for each subsection of the Notation Reference -(NR) are also linked from the @strong{See also} portion. - - -@node Other documentation -@subsection Other documentation - - -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 Learning Manual (LM) +@node About the Learning Manual (LM) +@unnumberedsubsec About the 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 @item -@ifhtml -The -@end ifhtml -@emph{@ref{Tutorial}}, -gives a gentle introduction to typesetting music. First time -users should start here. +@ref{Tutorial}: gives a gentle introduction to typesetting music. +First time users should start here. @item -@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! +@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 -@emph{@ref{Working on LilyPond projects}}, -discusses practical uses of LilyPond and how to avoid some common -problems. +@ref{Working on LilyPond projects}: discusses practical uses of +LilyPond and how to avoid some common problems. @item -@emph{@ref{Tweaking output}}, -shows how to change the default engraving that LilyPond -produces. +@ref{Tweaking output}: shows how to change the default engraving +that LilyPond produces. @end itemize -@subheading Notation Reference (NR) +@node About the Music Glossary (MG) +@unnumberedsubsec About the Music Glossary (MG) + +@cindex idiom +@cindex jargon +@cindex terminology +@cindex foreign languages +@cindex language -This book explains all the LilyPond commands which produce notation. It -assumes that readers are familiar with the concepts in the Learning -manual. +@ref{Top,Music glossary,,music-glossary}: +this explains musical terms, and includes translations to various +languages. 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. -All of this needs to be rewritten after GDP, anyway. -@ignore +@node About the Notation Reference (NR) +@unnumberedsubsec About the 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. @itemize @item -@emph{@r ef{Basic notation}}, +@ruser{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 -@emph{@r ef{Instrument-specific notation}}, +@ruser{Specialist 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 -@emph{@r ef{Advanced notation}}, -discusses topics grouped by notation construct. This section gives -details about complicated or unusual notation. - -@item -@emph{@r ef{Changing defaults}}, -explains how to fine tune layout. +@ruser{Input syntax}: @item -@emph{@r ef{Non-musical notation}}, -discusses non-musical output such as titles, multiple movements, -and how to select which MIDI instruments to use. +@ruser{Non-musical notation}: @item -@emph{@r ef{Spacing issues}}, +@ruser{Spacing issues}: discusses issues which affect the global output, such as selecting paper size or specifying page breaks. @item -@emph{@r ef{Interfaces for programmers}}, -explains how to create music functions. +@ruser{Changing defaults}: -@end itemize +@item +@ruser{Interfaces for programmers}: +explains how to create music functions with scheme. +@end itemize -@subsubheading Appendices -This book contains useful reference charts. +The NR also contains appendices with useful reference charts. @itemize @item -@ifhtml -The -@end ifhtml -@emph{@r ef{Literature list}}, -contains a set of useful reference books for those who wish to know -more on notation and engraving. +@ruser{Literature list}: +contains a set of useful reference books for those who wish to +know more on notation and engraving. @item -The -@emph{@r ef{Scheme tutorial}}, +@ruser{Scheme tutorial}: presents a short introduction to Scheme, the programming language that music functions use. @item -@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. +@ruser{Notation manual tables}: +are a set of tables showing the chord names, MIDI instruments, a +list of color names, and the Feta font. @item -@emph{@r ef{Templates}}, +@ruser{Templates}: of LilyPond pieces. Just cut and paste a template into a file, add notes, and you're done! @item -The -@emph{@r ef{Cheat sheet}}, +@ruser{Cheat sheet}: is a handy reference of the most common LilyPond commands. @item -The -@emph{@r ef{LilyPond command index}}, +@ruser{LilyPond command index}: is an index of all LilyPond @code{\commands}. @item -The -@emph{@r ef{LilyPond index}}, +@ruser{LilyPond index}: is a complete index. @end itemize -@end ignore - -@subheading Program usage +@node About the Application Usage (AU) +@unnumberedsubsec About the Application Usage (AU) This book explains how to execute the program and how to integrate LilyPond notation with other programs. @@ -933,27 +894,27 @@ LilyPond notation with other programs. @itemize @item -@emph{@rprogram{Install}}, +@rprogram{Install}: explains how to install LilyPond (including compilation if desired). @item -@emph{@rprogram{Setup}}, +@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}}, +@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. +@rprogram{LilyPond-book}: +explains the details behind creating documents with in-line music +examples, like this manual. @item -@emph{@rprogram{Converting from other formats}}, +@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. @@ -961,34 +922,26 @@ formats to the @code{.ly} format. @end itemize +@node About the Snippet List (SL) +@unnumberedsubsec About the Snippet List (SL) -@subsubheading Other information +@cindex snippets +@cindex LSR -There are a number of other places which may be very valuable. +The Snippet List shows a selected set of LilyPond snippets from the +@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository} +(LSR). It is in the public domain. -@itemize -@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. +Please note that this document is not an exact subset of LSR. LSR +is running a stable LilyPond version, so any snippet which +demonstrates new features of a development version must be added +separately. These are stored in @file{input/new/} in the LilyPond +source tree. -@cindex snippets -@cindex LSR +The list of snippets for each subsection of the Notation Reference +(NR) are also linked from the @strong{See also} portion. + +@itemize @item The @ifhtml @@ -1001,8 +954,14 @@ 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. +@end itemize + +@node About the Internals Reference (IR) +@unnumberedsubsec About the Internals Reference (IR) + +@itemize @item The @iftex @@ -1026,6 +985,14 @@ HTML document, these subsections have clickable links. @end itemize +@node Other documentation +@unnumberedsubsec Other documentation + +FIXME: most of this should go higher up. Discuss News, mailist +archives, ...? + +There are a number of other places which may be very valuable. + 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 @@ -1071,3 +1038,5 @@ files and HTML from the web site, which can be found at @uref{http://@/www@/.lilypond@/.org/}. + + diff --git a/Documentation/user/rhythms.itely b/Documentation/user/rhythms.itely index b20c93d8ac..83ecb95d70 100644 --- a/Documentation/user/rhythms.itely +++ b/Documentation/user/rhythms.itely @@ -8,6 +8,33 @@ @c \version "2.11.38" +@ignore +GDP TODO list + +\compressMusic -> \scaleDurations. +approved by Han-Wen; just needs somebody to kick up a fuss about +it. + +1.2.3.1 Time signature +Needs an example of beatLength, which is broken (see my recent +mail +to -bug). What to do? For now I've left a paragraph of text +which really +needs to be inserted with an example in a snippet. + +1.2.3.4 Polymetric notation +Quite extensive changes. Could you please check through. Divided +into three +sections. Necessarily uses tweaks. I've also left an @lsr under +@seealso +Snippets - is this permitted or is @lsr now verboten? This +snippet is too +long to include, but seems relevant. +A snippet "grouping beats" hasn't yet appeared (only sent to vv a +couple of +days ago). Text left in Snippets: with TODO. +@end ignore + @node Rhythms @section Rhythms diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely index 442082c5e3..3cfd80ce65 100644 --- a/Documentation/user/spacing.itely +++ b/Documentation/user/spacing.itely @@ -9,9 +9,44 @@ @c \version "2.11.38" -@c A menu is needed before every deeper *section nesting of @node's; run -@c M-x texinfo-all-menus-update -@c to automatically fill in these menus before saving changes +@ignore +GDP TODO list + +Negative numbers are allowed: +> Are you sure? The following works well +> \paper{ +> first-page-number = -2 +> } +> and prints page number -1 on the second page, for example. + + +- default paper size is A4. + + +In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it +states: + +"@code{layout-set-staff-size} does not change the distance between +the +staff lines." + +Could we add a sentence: +"Use instead the pair fontSize = #@var{N} + \override StaffSymbol #'staff-space = #(magstep +@var{N}) +inside the Staff context to change the size of the font and the +distance between +staff lines accordingly." + +Actually I found, that the @internalsref{StaffSymbol} at line 481 +sends to an uncomplete +documentation. The property staff-space is not explained here. I +thought Y-extent might be of +help, but it is in turn explained by x-space which again is +missing from the list. Who has the +knowledge to fix this? + +@end ignore @node Spacing issues @chapter Spacing issues diff --git a/THANKS b/THANKS index ff5d8abb3b..fbda83327d 100644 --- a/THANKS +++ b/THANKS @@ -31,6 +31,8 @@ Jay Hamilton - NR Rewriter Till Retting - NR Rewriter Ralph Palmer - NR Rewriter Patrick McCarty - NR Rewriter +Andrew Hawryluk - NR Rewriter +Jonathan Kulp - NR Rewriter Kurt Kroon - Glossary Updates Alard de Boer - Formatting Michael Rasmussen - Formatting -- 2.39.5